Firmware builder usage


#1

Introduction

The firmware builder subsystem offers its services through a HTTP API. We want to describe the steps involved when it receives such HTTP requests:

  • Pull the source code including git submodules from the firmware source code repository.
  • Decode the firmware specifications (environment and features) from parameters of the HTTP POST request.
  • Amend the source code according to these specifications.
  • Pass it down to the cross compiler ("avr-gcc" or “xtensa-lx106-elf-gcc”).
  • When successful, the HTTP response contains a binary payload representing the “.hex” or “.bin” file to be uploaded to the MCU flash memory.

The format of the firmware builder HTTP endpoint is:

https://swarm.hiveeyes.org/api/hiveeyes/testdrive/area-42/node-1/firmware.hex

Please have a look at firmware builder development for more details.


Firmware builder beta release
About the "generic" firmware
#2

Synopsis

This is an example about how things are working in general to get the idea. For demonstration purposes, we use a flexible firmware for ESP8266 talking MQTT, node-wifi-mqtt.ino.

Build and download firmware

http \
    --timeout=300 \
    --download \
    POST \
    https://swarm.hiveeyes.org/api/hiveeyes/testdrive/area-42/node-1/firmware.bin \
    ref=master \
    update_submodules=false \
    path=node-wifi-mqtt \
    architecture=esp \
    makefile=Makefile \
    WIFI_SSID_1="the-beekeepers" \
    WIFI_PASS_1="wifi-secret" \
    MQTT_BROKER="test.mosquitto.org" \
    MQTT_USERNAME="hotzenplotz@example.org" \
    MQTT_PASSWORD="mqtt-secret" \
    MQTT_TOPIC="hiveeyes/testdrive/raeuberhoehle/schatzkammer/data.json" \
    MEASUREMENT_INTERVAL="60 * 1000" \
    DEEPSLEEP_ENABLED="true" \
    SENSOR_HX711="true" \
    SENSOR_DHTxx="false" \
    LOADCELL_ZERO_OFFSET="53623.0f" \
    LOADCELL_KG_DIVIDER="18053"

Success

When successful, the output should be like:

HTTP/1.1 200 OK
Channel-Id: /hiveeyes/testdrive/area-42/node-1/firmware.bin
Content-Type: application/octet-stream

Downloading to "hiveeyes_node-wifi-mqtt_esp-esp8266_20170421T044305_0a30bf43_4db5b00a-2a94-4a24-9676-6817550e229b.bin"
Done. 274.39 kB in 0.00148s (180.46 MB/s)

Result

Proof:

xtensa-lx106-elf-strings \
    hiveeyes_node-wifi-mqtt_esp-esp8266_20170421T044305_0a30bf43_4db5b00a-2a94-4a24-9676-6817550e229b.bin \
    | egrep -A3 '(the-beekeepers|test.mosquitto.org)'

the-beekeepers
wifi-secret
[...]
--
test.mosquitto.org
hotzenplotz@example.org
mqtt-secret
hiveeyes/testdrive/raeuberhoehle/schatzkammer/data.json

echo $?
0

#3

Derive MQTT_TOPIC from channel address

As the full channel address information is encoded into the API URL already:

The appropriate “MQTT_TOPIC” value, which was set manually in the former example:

… can be automatically computed from that.

Example

Note that we use address components with different values here:

TELEMETRY_SITE=area-53
TELEMETRY_NODE=node-77

Just issue:

http --timeout=300 --download POST \
    https://swarm.hiveeyes.org/api/hiveeyes/testdrive/area-53/node-77/firmware.bin \
    ref=master \
    update_submodules=false \
    path=node-wifi-mqtt \
    architecture=esp \
    makefile=Makefile

See…?

./xtensa-strings hiveeyes_node-wifi-mqtt_esp-esp8266_20170421T045511_0a30bf43_924d2b08-4fc6-4cf6-a4e4-5536fca8f3ef.bin \
  | grep 'hiveeyes/testdrive'

hiveeyes/testdrive/area-53/node-77/data.json