Skip to content

Experimental USB deployment

ESP8266 with 4 MiB flash and Arduino MKR WiFi 1010 have a local USB path. It does not require a management server, Wi-Fi setup or new network credentials. These are experimental targets, not ESP32 feature parity. Run SDK commands below from the checkout installed by Quickstart.

Prepare host tools and identify the board

Both targets need the Python environment from ./micros setup. For ESP8266, install Python 3.10, CMake and Ninja on PATH. Apple Silicon also needs Rosetta for the pinned Intel compiler. For MKR, install Arduino CLI and a complete ARM GCC 10+ toolchain (arm-none-eabi-gcc, g++, objcopy) on PATH. init --phase prepare downloads pinned platform dependencies; it does not flash. MKR setup installs Arduino SAMD core 1.8.13 into Arduino's user data directory if absent. Other downloaded dependencies stay in the SDK's build/ directory.

./micros discover --port PORT --json

Replace PORT with the exact USB interface. Discovery may reset the board. Record its platform and twelve-digit device_id; do not identify hardware by its port name alone. A stock MKR sketch may not expose its NINA MAC until the base is installed. Select only the physical board you intend to replace.

Build and install the base

Choose one target:

./micros init HARDWARE_ID --platform esp8266 --phase prepare
./micros init HARDWARE_ID --platform esp8266 --phase flash --port PORT

./micros init HARDWARE_ID --platform samd21 --phase prepare --compiler-dir /path/to/arm-gcc/bin
./micros init HARDWARE_ID --platform samd21 --phase flash --port PORT --compiler-dir /path/to/arm-gcc/bin

Flash replaces firmware and application banks. It preserves existing network settings, which can reconnect an already configured board to its previous server. It does not create new credentials or enroll the board in a server. Keep the SDK's .micros/ state: pairing retains the exact ELF needed for service builds. --phase connect --firmware PATH/TO/EXACT.elf pairs an already installed matching base without flashing; a different ELF is rejected.

For an unidentified stock MKR, use a temporary local name for init, then read discover after installation and pair with --phase connect using its hardware ID.

Create a target-specific starter

From the directory where you keep applications, use the SDK on PATH:

micros new my-mkr-application --platform samd21
# Or, for ESP8266:
micros new my-esp8266-application --platform esp8266

New projects contain the three simulated climate services and units/host.toml, without a placeholder board unit. Successful ./micros enroll creates the real unit automatically, selecting arduino_mkr_wifi_1010 or esp8266_4mb from the detected board. It omits ESP32-only flash_mb and gives each service a 1024-byte worker stack on MKR or 1536 bytes on ESP8266. The new --platform flag remains accepted for compatibility.

If you used manual USB provisioning without enrollment, copy units/host.toml to units/HARDWARE_ID.toml, retain all three services and both channels, and add:

[unit]
device_id = "HARDWARE_ID"

[board]
profile = "arduino_mkr_wifi_1010" # Use esp8266_4mb for ESP8266.

Use the observed twelve-digit hardware ID. Set each service's memory.stack_bytes to 1024 on MKR or 1536 on ESP8266. Size stacks for changed behavior and inspect runtime headroom. There is no external sensor, fan or display to wire.

From the application directory, with MICROS_SDK still exported:

./micros compose -d HARDWARE_ID
./micros deploy -d HARDWARE_ID --via usb --port PORT --dry-run
./micros deploy -d HARDWARE_ID --via usb --port PORT
./micros status -d HARDWARE_ID --via usb --port PORT
./micros logs -d HARDWARE_ID --via usb --port PORT

Expect all three services running, no pending trial, and Simulated climate lines with fan ON/OFF transitions. A successful upload alone is not successful activation. If activation fails, inspect status and logs before another write. USB serial opening may reset ESP8266, so compare observations within the same boot when testing timing. For network enrollment, return to Set up a board.