OS installation

Write nodexOS to an SD card

A new board needs nodexOS once. After that, OS and supervisor updates arrive over the network, and the board rolls back on its own if an update doesn't boot.

1. Download the image

   In your fleet, click Add device, pick the device type and download nodexOS. The nodexa-os-<version>-<board>.wic.zip file already carries the fleet's provisioning, and the WiFi network if you entered one.

2. Write it to a microSD card

   The easiest way is balenaEtcher (Windows, macOS, Linux): pick the .wic.zip as-is, pick the card, and flash. From a terminal instead:

   macOS

   Copy

   diskutil list                      # find the card, e.g. /dev/disk4
   diskutil unmountDisk /dev/disk4
   unzip -p nodexa-os-<version>-<board>.wic.zip '*.wic' | sudo dd of=/dev/rdisk4 bs=4m status=progress
   sync && diskutil eject /dev/disk4

   Linux

   Copy

   lsblk                              # find the card, e.g. /dev/sdb
   sudo umount /dev/sdb?*
   unzip -p nodexa-os-<version>-<board>.wic.zip '*.wic' | sudo dd of=/dev/sdb bs=4M status=progress conv=fsync

   dd overwrites the whole disk you give it. Check the device name in diskutil list or lsblk twice; picking your computer's own disk erases it.

3. Boot the board from the card, as described below
4. Wait for the device to appear in the fleet's device list

   This takes a few minutes and needs Ethernet with DHCP, or the WiFi network you set when downloading.

Boot a BeagleBone Black

The board has its own eMMC storage. nodexOS boots once from the SD card, copies itself onto the eMMC, and from then on runs from the eMMC without the card.

1. Insert the card, hold the S2 (boot) button and power on

   Let go once the LEDs start. Without S2 the board boots whatever is already on its eMMC.

2. Wait while it copies itself to the eMMC

   This starts on its own. USR2 blinks while copying and goes solid when it's done; USR0 blinks whenever nodexOS is running. The board then powers itself off.

3. Remove the SD card and power on again

   No need to hold S2. The board now boots nodexOS from the eMMC.

Serial console

Connect a USB-to-TTL (3.3V) adapter to the debug UART header at 115200 8N1. On macOS the adapter shows up as /dev/tty.usbserial-*.

If the eMMC copy doesn't seem to happen

systemctl status nodexa-flash-emmc.service --no-pager
journalctl -u nodexa-flash-emmc.service --no-pager
ls /var/lib/nodexa/nodexa-emmc-flash/done   # exists once the copy has finished

To copy again, delete that done file, or run nodexa-flash-emmc by hand (nodexa-flash-emmc --help lists its options).

Check the device

Log in on the serial console or the board's terminal in the dashboard, then:

cat /etc/os-release                        # nodexOS version
systemctl status nodexa-agent --no-pager   # supervisor running
journalctl -u nodexa-agent -n 50           # registering with the cloud

More in Debugging.

Write nodexOS to an SD card

A new board needs nodexOS once. After that, OS and supervisor updates arrive over the network, and the board rolls back on its own if an update doesn't boot.

1. Download the image

   In your fleet, click Add device, pick the device type and download nodexOS. The nodexa-os-<version>-<board>.wic.zip file already carries the fleet's provisioning, and the WiFi network if you entered one.

2. Write it to a microSD card

   The easiest way is balenaEtcher (Windows, macOS, Linux): pick the .wic.zip as-is, pick the card, and flash. From a terminal instead:

   macOS

   Copy

   diskutil list                      # find the card, e.g. /dev/disk4
   diskutil unmountDisk /dev/disk4
   unzip -p nodexa-os-<version>-<board>.wic.zip '*.wic' | sudo dd of=/dev/rdisk4 bs=4m status=progress
   sync && diskutil eject /dev/disk4

   Linux

   Copy

   lsblk                              # find the card, e.g. /dev/sdb
   sudo umount /dev/sdb?*
   unzip -p nodexa-os-<version>-<board>.wic.zip '*.wic' | sudo dd of=/dev/sdb bs=4M status=progress conv=fsync

   dd overwrites the whole disk you give it. Check the device name in diskutil list or lsblk twice; picking your computer's own disk erases it.

3. Boot the board from the card, as described below
4. Wait for the device to appear in the fleet's device list

   This takes a few minutes and needs Ethernet with DHCP, or the WiFi network you set when downloading.

Boot a Raspberry Pi 4

1. Insert the card and power on

   The Pi 4 boots from the microSD card by default, so there's no button or switch to set.

2. Keep the card in

   The Pi runs nodexOS from the card, so leave it in the board.

Use a good-quality card and the official power supply. Most unexplained reboots and corrupted cards come from a weak supply.

Check the device

Log in on the serial console or the board's terminal in the dashboard, then:

cat /etc/os-release                        # nodexOS version
systemctl status nodexa-agent --no-pager   # supervisor running
journalctl -u nodexa-agent -n 50           # registering with the cloud

More in Debugging.

Write nodexOS to an SD card

A new board needs nodexOS once. After that, OS and supervisor updates arrive over the network, and the board rolls back on its own if an update doesn't boot.

1. Download the image

   In your fleet, click Add device, pick the device type and download nodexOS. The nodexa-os-<version>-<board>.wic.zip file already carries the fleet's provisioning, and the WiFi network if you entered one.

2. Write it to a microSD card

   The easiest way is balenaEtcher (Windows, macOS, Linux): pick the .wic.zip as-is, pick the card, and flash. From a terminal instead:

   macOS

   Copy

   diskutil list                      # find the card, e.g. /dev/disk4
   diskutil unmountDisk /dev/disk4
   unzip -p nodexa-os-<version>-<board>.wic.zip '*.wic' | sudo dd of=/dev/rdisk4 bs=4m status=progress
   sync && diskutil eject /dev/disk4

   Linux

   Copy

   lsblk                              # find the card, e.g. /dev/sdb
   sudo umount /dev/sdb?*
   unzip -p nodexa-os-<version>-<board>.wic.zip '*.wic' | sudo dd of=/dev/sdb bs=4M status=progress conv=fsync

   dd overwrites the whole disk you give it. Check the device name in diskutil list or lsblk twice; picking your computer's own disk erases it.

3. Boot the board from the card, as described below
4. Wait for the device to appear in the fleet's device list

   This takes a few minutes and needs Ethernet with DHCP, or the WiFi network you set when downloading.

Boot a Variscite DART

1. Set the board to boot from SD

   This is a jumper or DIP switch on the carrier board, and its position depends on the carrier and its revision. Check Variscite's documentation for your board.

2. Insert the card and power on

Serial console

115200 8N1 on the debug UART (ttymxc0). If the board doesn't come up, capture the whole U-Boot and kernel log from here first; it's the only view into early boot.

Check the device

Log in on the serial console or the board's terminal in the dashboard, then:

cat /etc/os-release                        # nodexOS version
systemctl status nodexa-agent --no-pager   # supervisor running
journalctl -u nodexa-agent -n 50           # registering with the cloud

More in Debugging.

Flash nodexOS onto the board

A new board needs nodexOS before you can deploy apps to it. You only do this once; after that, OS updates arrive over WiFi.

1. Download the firmware

   Open your ESP32 fleet, click Add device, choose your board and enter your WiFi details, then download the .bin file (for example nodexa-os-0.1.2-esp32.bin). The file already contains your fleet and WiFi settings.

2. Install esptool in a virtual environment

   macOS and Linux:

   Copy

   python3 -m venv espflash
   source espflash/bin/activate
   pip install esptool

   Windows (PowerShell):

   Copy

   python -m venv espflash
   espflash\Scripts\Activate.ps1
   pip install esptool

   In a new terminal, run the activate line again before using esptool.py.

3. Find the board's serial port

   Connect the board over USB with a data cable (not a charge-only one), then list the ports.

   macOS, usually /dev/cu.usbserial-0001:

   Copy

   ls /dev/cu.usbserial-* /dev/cu.usbmodem* /dev/cu.SLAB_USBtoUART* 2>/dev/null

   Linux, usually /dev/ttyUSB0:

   Copy

   ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

   Windows: find the COM port (for example COM3) under Ports (COM & LPT) in Device Manager. If no port appears on any system, install the board's USB driver (CP210x or CH340).

4. Erase the flash

   Replace the port with yours from the previous step.

   Copy

   esptool.py --port /dev/cu.usbserial-0001 erase_flash

5. Write nodexOS

   Use the path of the file you downloaded. It must be written at offset 0x0.

   Copy

   esptool.py --port /dev/cu.usbserial-0001 --baud 460800 write_flash 0x0 ~/Downloads/nodexa-os-<version>-esp32.bin

6. Reset the board

   Press the board's EN/RST button or reconnect the USB cable. The board joins your WiFi and shows up in the fleet's device list within a few minutes.

   If you didn't enter WiFi details, the board opens a WiFi network named Nodexa-XXXXXX. Join it and open http://192.168.4.1 to choose a network.

Troubleshooting

esptool.py says Failed to connect while flashing an ESP32

Hold the board's BOOT button, run the command again, and let go once Connecting... appears. Also close anything else using the port, such as a serial monitor. If it connects but writing fails, drop the speed to --baud 115200.

Install Nodex Nomad on a PC

Flash the image onto an SD card, put the card in a USB card reader, plug it into the PC and boot from it. A USB card reader works like a normal USB drive, so the PC boots from it just as it would from a pen drive. A 16 GB card is plenty: on first boot the data partition grows to fill it.

What the PC needs

Supported network cards

Wired:

Wi-Fi:

1. Download the image

   Open the fleet, click Add device and choose Nodex Nomad. To use Wi-Fi, enter the network name and password there: they're built into the image. Download the .wic.zip file (for example nodexa-os-<version>-generic-x86_64.wic.zip).

2. Flash the card

   The easy way: open balenaEtcher, pick the .wic.zip file (no need to unzip it), pick the card and click Flash.

   Or from the terminal (macOS): find the card first. It's the ~16 GB disk marked "external, physical", for example /dev/disk4.

   Copy

   diskutil list                      # find the card
   diskutil unmountDisk /dev/disk4
   unzip -p nodexa-os-<version>-generic-x86_64.wic.zip '*.wic' | sudo dd of=/dev/rdisk4 bs=4m status=progress
   sync && diskutil eject /dev/disk4

   Double-check the disk number. dd overwrites the whole disk without asking.

3. Set up the PC's firmware

   Open the firmware settings (usually F2 or Del at power-on), turn off Secure Boot, and make sure the PC boots in UEFI mode, not Legacy/CSM.

4. Connect to the network

   Plug in an Ethernet cable on a network with DHCP, or rely on the Wi-Fi network you entered when downloading. If both are connected, Ethernet is used. Check that the PC's network card is in the list above.

5. Boot from the card

   Plug the card reader, with the card in it, into the PC. Power on and press the one-time boot menu key (usually F12, F11, F8 or Esc). Choose the card reader, which may be listed as "USB" or "UEFI: <reader name>".

6. Check it on the PC's screen

   Log in as root (no password), then run:

   Copy

   cat /etc/os-release                        # NAME="Nodex Nomad"
   systemctl status nodexa-grow-data nodexa-agent
   lsblk                                      # p6 (nodexa-data) fills the rest of the card
   ip -br addr                                # has an IP address
   journalctl -u nodexa-agent -n 50           # registering with the cloud
   grub-editenv /boot/nodexa.env list 2>/dev/null || cat /proc/cmdline   # nodexa.slot=a

7. Check it in the dashboard

   The device shows up in your fleet with architecture x86_64. From its page you can view its logs, open the SSH terminal and deploy containers to it (see Deploy apps).

Specification

OS updates

When a new Nodex Nomad version is published, start an OS update from the device page. The PC installs it on its other system slot and reboots into it. Afterwards, cat /proc/cmdline shows nodexa.slot=b (or a, after the next update).

If it doesn't boot