User Tools

Site Tools


UKHASnet Gateway Dongle

A USB dongle built by Matt which receives UKHASnet packets and relays them to the backend server using an inbuilt wifi client device.


Binaries here (most recent first)

Stable (for use with v1.40 ESP SDK firmware)

19/03/17 - e238e48

14/04/16 - d388884

30/03/16 - 38f7419

Building firmware

  1. Switch to the chibi branch and cd into firmware-basestation/.
  2. Fetch ChibiOS with $ git submodule update --init
  3. Ensure you have gcc-arm-embedded available and type $ make to build the firmware

Flashing firmware

The easiest way to flash the firmware is via DFU.

  1. Hold down the “BOOT” button on the board whilst plugging it into a USB port.
  2. Check the device is seen by dfu-util with $ dfu-util --list
  3. Flash with: $ dfu-util -a 0 -s 0x08000000 -d 0483:df11 -D path/to/firmware.bin


  • Wifi (green) - solid on when associated, flickers off during sending data to server
  • 868 (red) - flashes briefly on reception of a valid packet
  • Aux (red) - unused

Reporting (temperature/humidity)

  • The dongle will send a UKHASnet packet straight to the server every 3 minutes
    • 0tT27.39H35.8X00:38f7419[JX0]
  • If the HTU21 temperature/humidity sensor (along with 100nF and 4k7 pullups) are fitted the temperature and humidity will be included
  • The X field is followed by an error byte (00 - FF)
    • 0 - HTU temp/humidity request timeout (sensor not fitted?)
    • 1 - unused
    • 2 - unused
    • 3 - unused
    • 4 - unused
    • 5 - unused
    • 6 - unused
    • 7 - unused

Serial Terminal Usage

Connect to the USB serial terminal: screen /dev/tty.usbmodem301 (or use whatever terminal you wish).

You can type help to get a list of commands.

Setting node name

  • Type esp origin to see the current node name.
  • Type esp origin MYNODE to set the node name.

Connecting to wifi

  • Type esp ap to see the current SSID and password.
  • Type esp ap MYSSID MYPASS to set the SSID and password.

The green LED will be solid on when the wifi is associated.

You may need to reset the ESP a couple of times after joining a new wifi network: esp reset.

Showing IP address

  • Type esp ip to see the node's IP address

Viewing packets

  • Type show packet to have received packets printed to the serial terminal
    • Packet: 2kV2.5T017.3H58[MB1,WIGHTLINK] (-80dBm)
  • Type show none to revert this change.

Dongle firmware version

  • Type ver to see the current dongle firmware version (first 7 chars of the git commit hash - e.g. ed39b22)
  • You will see -dirty appended if you're running a test firmware, e.g. ed39b22-dirty

Updating ESP firmware

Type esp ver to see the current ESP SDK version number.

The dongle can be used to put the ESP into bootloader mode and pass through the serial terminal so that you can just point esptool at it.

  • Type esp pt boot, then wait until ESP entering bootloader… done appears.
  • Disconnect the serial terminal and point esptool at it.

You will need to reboot (unplug/plug) the dongle to return to normal operation.


This is obsolete, use a newer version


For dongle firmwares up to and including e3444ef


This is the most recent ESP firmware that retains support for 4MBit (512k) flash ESP8266 devices, which most (all?) of the dongles are. (Check that irom0text.bin is 240kB or less - it's around 350kB in later firmwares).


You need to flash:

  • at/noboot/eagle.flash.bin to 0x00000
  • at/noboot/eagle.irom0text.bin to 0x40000
  • at/noboot/blank.bin to 0x3e000 and 0x7e000
  • at/noboot/esp_init_data_default.bin to 0x7c000

If using esptool, use:

python --port /dev/tty.usbmodem301 write_flash 0 at/noboot/eagle.flash.bin 0x40000 at/noboot/eagle.irom0text.bin 0x3e000 at/blank.bin 0x7e000 at/blank.bin 0x7c000 at/esp_init_data_default.bin

Dongle firmware (major) changelog

Some git sha1s and the corresponding change log is here, in chronological order (most recent last).

  • e3444ef is the last firmware to use the v0.9.2.2 ESP firmware
  • ed39b22 onwards requires ESP SDK version 1.40 (AT version 0.50)
  • 38f7419 adds temperature/humidity reporting
  • d388884 fixes firmware hanging when the HTU21D temperature/humidity sensor is not fitted
  • 3813886 RFM timeout, reboot if no packets received in a minute. 2) Clear ESP receive buffer only immediately before we send. 3) Check for SEND OK as termination criterion for CIPSEND. 4) 16 mailbox items instead of 8
  • 1ab59f8 Adds age reporting of packets when uploaded, to enable server to correct for the time delay between dongle receiving the packet and it getting POST'ed to the server
  • 2f175a3 Each packet is retried ESP_RETRIES_MAX (=3) times, then discarded
  • 147c245 Packet age bug fixed. Mempool alloc fail now discards oldest mail in queue.
  • e238e48 Updated chibi to latest stable_3.0.x
jon/gateway-dongle.txt · Last modified: 2020/06/27 23:02 (external edit)