la_machine_2024-06-29.mp4
La Machine software is written in Erlang and runs on AtomVM virtual machine.
La Machine runs on an ESP32-C3 with 16 MB of external flash. The partition layout is:
| Partition | Offset | Size |
|---|---|---|
| nvs | 0x009000 |
0x006000 |
| phy_init | 0x00F000 |
0x001000 |
| factory | 0x010000 |
0x120000 |
| boot.avm | 0x130000 |
0x100000 |
| sounds | 0x230000 |
0xDD0000 |
- factory: AtomVM virtual machine with necessary codecs.
- boot.avm: La Machine Erlang code packed with AtomVM libraries.
- sounds: sounds archive (
sounds.bin) with a SHA1 integrity checksum appended. The code verifies at runtime that the sounds partition matches the compiled index.
GitHub action builds an optimized image of La Machine including AtomVM virtual
machine with necessary codecs. It is artifact named la_machine.img of
Build workflow.
Please note that La Machine can only be flashed when it is not deep sleeping. You can press its button to wake it up.
It can be flashed with ESP-IDF esptool on macOS as follows:
esptool.py --chip esp32c3 --port /dev/cu.usbmodem* write_flash 0 ~/Downloads/la_machine.img
The port may vary on your platform.
When flashing the whole image, La Machine must go through self-test and calibration on first boot. See FLASHING-AND-CALIBRATION.md for details.
Once La Machine is flashed (which should be the case when you got it), you can update the code using this repository.
To compile source code of La Machine, you need Erlang/OTP (for example OTP28)
and rebar3. The partition map differs from standard AtomVM deployments
and you need to pack La Machine code with AtomVM libraries. You can use either the
full package atomvmlib.avm or
only estdlib.avm and eavmlib.avm.
rebar3 atomvm packbeam -p -e ~/Downloads/atomvmlib-v0.6.6.avm
rebar3 atomvm esp32_flash -p /dev/cu.usbmodem* -o 0x130000
The sounds partition can be reflashed independently:
esptool.py --chip esp32c3 --port /dev/cu.usbmodem* write_flash 0x230000 _build/generated/sounds.bin
If you change the sound directory (add some, remove some or update any sound),
the sound index will be rebuilt. The sound index is generated at compile time
and included into the la_machine.avm file. So you need to flash both
the sounds partition and the Erlang code.
Please note that La Machine code currently expects only MP3 sounds mono at
44.1kHz or 48kHz. scripts/build_assets.escript script will check that. The
virtual machine can play either MP3 or AAC sounds but you would need to make
some change in the Erlang code.
La Machine comes with a scenario editor created with Processing IDE. You can open the sketch directly from Processing IDE or use one of the binary applications that are part of the release and generated by Build editor workflow. When you open the editor, you need to choose the choreographies.json file. On macOS, you may need to go into "System settings" -> "Privacy & Security" to allow the editor to open as it's a self-signed application.
Alternatively, you can manually edit choreographies.json.
When you rebuild la_machine.avm with rebar3, the choreographies are embedded into
the Erlang code using scripts/build_assets.escript.