====== UKHASnet Gateway Dongle ======

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

===== Firmware =====

Binaries here (most recent first)

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

19/03/17 - {{:jon:ukhasnet-dongle-e238e48.tar.gz|e238e48}}

14/04/16 - {{:jon:ukhasnet-dongle-d388884.tar.gz|d388884}}

30/03/16 - {{:jon:ukhasnet-dongle-38f7419.tar.gz|38f7419}}
==== Building firmware ====

  - Firmware is in: [[https://github.com/mattbrejza/magnet-node.git]]
  - Switch to the ''chibi'' branch and ''cd'' into ''firmware-basestation/''.
  - Fetch ChibiOS with ''$ git submodule update %%--%%init''
  - Ensure you have [[https://launchpad.net/gcc-arm-embedded|gcc-arm-embedded]] available and type ''$ make'' to build the firmware

==== Flashing firmware ====
The easiest way to flash the firmware is via DFU. 
  - Hold down the "BOOT" button on the board whilst plugging it into a USB port.
  - Check the device is seen by dfu-util with ''$ dfu-util %%--%%list''
  - Flash with: ''$ dfu-util -a 0 -s 0x08000000 -d 0483:df11 -D path/to/firmware.bin''

===== LEDs =====
  * 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 [[:packet_format|UKHASnet packet]] straight to the server every 3 minutes
    * ''0tT27.39H35.8%%X%%00: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.

=== v0.9.2.2 ===

**This is obsolete, use a newer version**

Download: {{:jon:v0.9.2.2firmware.zip|}}

For dongle firmwares up to and including ''e3444ef''

=== v1.40 ===

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).

Download: {{:jon:at_v0.50_on_esp_iot_sdk_v1.4.0_150918.zip|}}

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 esptool.py %%--%%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