Skip to content

Limitations

Security

Nothing on this machine is access-controlled. The network features were built for a hobby machine on a home network, and they assume everyone who can reach the device is welcome to use it.

Remote desktop No authentication. Anyone on the same network can open the address, watch the screen and send keyboard and mouse input — that is, operate the machine
The file and app endpoints beside it Also unauthenticated, and in the released build. Anyone who can reach the remote desktop can also list, read, write and delete files, and start or stop apps
BLE console and debug service Starts at boot by default on Retro and on Modern (Tab5, NARYA v4); turn it off with the BLE Auto Start setting (ble_auto_start). The headless AtomS3R and StickS3 run it only in setup mode. While it runs it uses no pairing, no bonding and no encryption (deliberately, because pairing breaks Web Bluetooth on Windows): anyone in radio range can connect, look at running apps and their variables, start or stop them, read the log, and read and write ordinary files. It cannot be stopped without a reboot
Remote debugger over TCP No authentication. It listens on all interfaces
Wi-Fi credentials Stored in plain text on the device, in /home/wifi.toml (what the Wi-Fi page writes) or /etc/wifi.toml. 3.0.0's remote file services do not serve them over HTTP. In the development version they do: the file endpoints reach every path, keys and passwords included, so that /home can be backed up and restored over Wi-Fi. Over BLE they are readable only while BLE Setup is open on the machine
Service keys An API key for the speech service sits in plain text in /home/secrets.toml, kept like the Wi-Fi password: in the development version the file endpoints serve it over HTTP too, as they serve the rest of /home
Apps An app you download runs with the same rights as any other. There is no sandbox between apps and the filesystem

Use these features only on a network you trust, and at your own risk. Do not forward a port to the device from the internet. Wi-Fi can be kept off at boot with wifi_auto_start in Config, and BLE likewise with ble_auto_start (BLE Auto Start); once BLE is running it cannot be stopped without a reboot.

Differences from R2P2

Family mruby is based only on the core part of PicoRuby, and some gems used in PicoRuby's official R2P2 have been independently rewritten. As a result, there may be differences in the available classes and method behavior.

Differences Between PicoRuby and CRuby

PicoRuby is based on mruby, so some methods that are standard in CRuby may not be available.

Heap Size

Each Family mruby app runs as an independent Ruby VM, with its own heap and stack allocated on PSRAM.

Item Retro, StickS3, AtomS3R Modern Linux simulator, Linux program Studio
Standard app heap 500 KB 1024 KB 1536 KB 1536 KB
Heap with large_memory = 1 1024 KB 2048 KB 3072 KB 3072 KB
User apps at a time 3 5 5 5
large_memory apps at a time 2 1 1 1

max_apps in system_conf.toml lowers the number of user apps. The pool does not grow: an app runs out when no single free block is large enough, which can happen well before the total is used up. The Linux builds are 64-bit and need about 1.5 times the room for the same script, so they are about as tight as Modern; Studio is looser than any board, so check a large app on a board too.

You can check heap usage in the Monitor app.

Language support status

Language Status
Ruby (PicoRuby) The main language. Everything documented here
MicroPython Usable, with real limits: one Python app at a time, files read and written only whole (FmrbFile), strings that are bytes, and a smaller standard library. Drawing, sprites and sound are there. See MicroPython and BASIC
BASIC Feature-complete as of 2.0. Every known difference from Family BASIC V3 is catalogued. See MicroPython and BASIC
Lua A concept implementation. Not suitable for building a substantial application
C, TinyGo, Rust, Zig As WebAssembly apps, experimental, in the development version. Not on the ESP32-S3 boards (Retro, StickS3, AtomS3R). The SDK's names and shapes may still change

Waiting inside an app

Prefer Machine.delay_ms, which is FreeRTOS vTaskDelay underneath:

Machine.delay_ms(500)

Better still, do not block at all: return the number of milliseconds until you want to be called again from on_update, and let the message pump do the waiting. An app that blocks processes no events while it does.

This was worse before 2.0

In 1.0 the tick that drives PicoRuby's task switching had to be disabled: calling it from outside the VM corrupted the VM stack. That is fixed — ticks are now accumulated by a signal source and applied at one point in the scheduler — and the Task feature works. The Machine.delay_ms recommendation above is about not blocking, not about the old corruption.

File System Limitations

Item Details
Maximum file size Within LittleFS limits (a few MB recommended)
Maximum path length FmrbConst::MAX_PATH_LEN
File names ASCII recommended. Avoid Japanese characters and special symbols
Dir#seek / Dir#tell Not supported (ENOSYS). Use rewind and count from the beginning

Inter-App Message Size Limit

The payload for Pub/Sub publish / send_message is limited to 176 bytes after MessagePack encoding. If you exceed this limit, consider transferring data via files or splitting it across multiple messages.

Machine-specific limitations

Most limits apply to both machines. These do not.

Modern (M5Stack Tab5)

microSD Read and written through the P4's SDMMC host, at /mnt/sd (also /sd). There is no card-detect line, so a card is assumed to be in
Video out The built-in panel is the only output. No composite video
GROVE One port, not two
Battery-backed clock Present (RX8130). The timesync service sets it from the network once the machine is online; Set Clock is the manual way

| Mouse wheel | A USB mouse's wheel works only for a device named in /etc/hid_devices.toml. Plug the mouse in and the log prints the line to add |

Retro (narya-board)

Wi-Fi and BLE One radio, one at a time. Running the BLE console means Wi-Fi will not start, and vice versa
Touch No touch panel. A USB mouse is the pointer
Remote desktop Not available
Firmware Two chips to flash, and both must be on the same version or the system will not boot
Resident services Not carried in the Retro firmware. The clock, network and speech services are Modern only
WAV playback play_wav returns false. The audio is at the far end of a serial link, and shipping a clip across it before a note could sound is too slow to be worth it
Mouse wheel The same per-device rule as Modern

Headless boards (M5Stack StickS3, AtomS3R)

Desktop None. The board runs the one app named in startup_app (Welcome, as shipped) on its small screen (StickS3 240 x 135, AtomS3R 128 x 128)
Setting up Wi-Fi Over BLE from the Family mruby Console: power on with the button held to enter setup mode. With no Wi-Fi settings at all the board starts in setup mode by itself. BLE runs only in setup mode
Apps at a time Three, as on Retro (see Heap Size)

Studio (the browser build)

Network FmrbNet.request fetches through the browser, so a server that refuses cross-origin requests cannot be read. Sockets — Net::HTTP, WebSocket — are not there
Files /home and /app/usr are kept in the browser and nowhere else, and so are the settings. Everything outside them is built fresh on every reload. Download the archive to keep anything
Browsers Desktop Chrome and Firefox. Safari is untested; phones and tablets are not a target, because the machine wants a keyboard
One tab Open the page twice and only the first tab saves

See Family mruby Studio.