Skip to content

README.md

Latest commit

 

History

History
279 lines (205 loc) · 7.42 KB

README.md

File metadata and controls

279 lines (205 loc) · 7.42 KB
Raw

Golioth Pouch Gateway

Golioth Pouch Gateway is a device capable of connecting to Golioth cloud and serving as proxy for Bluetooth-only devices (nodes). All communication between Bluetooth nodes and cloud is end-to-end encrypted and authenticated. This means that gateway serves as untrusted two-way channel between Bluetooth devices and Golioth cloud.

Getting Started

Supported Hardware

This application should work on any board with support in Zephyr or nRF Connect SDK that has Bluetooth and Internet capability, though some custom configuration is likely required. The easiest way to get started is to use one of the following targets that are already configured for this application:

  • NXP FRDM-RW612
  • Nordic Thingy:91 X
  • Nordic nRF9160DK
  • Sentrius MG100 Gateway

Release Binaries

Pre-built firmware binaries for the above hardware are available in GitHub. We recommend using these binaries as the fastest way to get started.

Flashing the FRDM-RW612

  1. Install JLink Commander.

  2. Program the FRDM-RW612 Gateway Firmware.

    a. Connect to the device with JLink Commander

    <JLink Commander Executable> -device rw612 -if swd -speed 4000 -autoconnect 1

    where <JLink Commander Executable> is JLink.exe on Windows and JLinkExe on Linux and MacOS.

    b. Issue the following commands in JLink Commander

    If using Ethernet:

    loadfile frdm_rw612-ethernet.hex
reset
exit

    If using WiFi:

    loadfile frdm_rw612-wifi.hex
reset
exit

  3. (WiFi Only) Store WiFi AP credentials

    a. Open a serial connection to the rw612

    b. Store your credentials

    wifi cred add -s <your-wifi-ssid> -p <your-wifi-password> -k 1
wifi cred auto_connect
Flashing the Thingy:91 X

  1. Install the nrfutil CLI tool.

  2. Program the nRF9151 Serial Modem Firmware

    a. Position the SWD selection switch (SW2) to nRF91

    b. Issue the following command:

    nrfutil device program --firmware thingy91x_nrf9151.hex --x-family nrf91

  3. Program the nRF5340 Gateway Firmware

    a. Power cycle the device and position the SWD selection switch (SW2) to nRF53

    b. Issue the following command:

    nrfutil device program --firmware thingy91x_nrf5340.hex --x-family nrf53 --core application
Flashing the nRF9160DK

  1. Install the nrfutil CLI tool.

  2. Program the nRF9160 Serial Modem Firmware

    a. Position the SWD selection switch (SW10) to nRF91

    b. Issue the following command:

    nrfutil device program --firmware nrf9160dk_nrf9160.hex --x-family nrf91

  3. Program the nRF52840 Gateway Firmware

    a. Power cycle the device and position the SWD selection switch (SW10) to nRF52

    b. Issue the following command:

    nrfutil device program --firmware nrf9160dk_nrf52840.hex --x-family nrf52
Flashing the MG100

  1. Install the nrfutil CLI tool.

  2. Program the nRF52840 Gateway Firmware

    a. Connect the Tag-Connect adapter and Segger debugger to J5 on the PCBA

    b. Issue the following command:

    nrfutil device program --firmware mg100.hex --x-family nrf52

    c. Power cycle the device

Provisioning

To use the Gateway, it needs to be provisioned with credentials for Golioth. For demonstration purposes, the Gateway firmware uses Pre-Shared Keys (PSK). In production settings, Golioth recommends using certificates issued from customer owned Public Key Infrastructure (PKI).

  1. Create a Device in your Golioth Project.
  2. Connect to your Gateway over serial and issue the following commands:
settings set golioth/psk-id <psk-id>
settings set golioth/psk <psk>

where <psk-id> and <psk> are the device credentials you created in step 1.

Building from Source

Setup

Setup repo with NCS:

west init -m https://github.com/golioth/pouch-gateway.git --mf west-ncs.yml
west update
west patch apply

Build and run

Thingy:91 X

Serial modem firmware runs on the nRF9151 chip, providing LTE connectivity to the gateway over UART. Switch to serial modem manifest, build and flash by changing the SWD switch (SW2) to nRF91, then:

west config manifest.file ncs-serial-modem/west.yml
west update
west patch apply
west build -p -b thingy91x/nrf9151/ns pouch-gateway/ncs-serial-modem/
west flash

Gateway firmware runs on the nRF5340 chip. It runs the Bluetooth Host stack and communicates with the nRF9151 serial modem over UART for Internet access. Switch back to NCS manifest, build and flash by changing the SWD switch (SW2) to nRF53, then:

west config manifest.file west-ncs.yml
west update
west patch apply
west build -p -b thingy91x/nrf5340/cpuapp --sysbuild pouch-gateway/gateway/
west flash

nRF9160 DK

Serial modem firmware runs on the nRF9160 chip, providing LTE connectivity to the gateway over UART. Switch to serial modem manifest, build and flash by changing the SWD switch (SW10) to nRF91, then:

west config manifest.file ncs-serial-modem/west.yml
west update
west patch apply
west build -p -b nrf9160dk/nrf9160/ns pouch-gateway/ncs-serial-modem/
west flash

Gateway firmware runs on the nRF52840 chip. It runs the Bluetooth Host stack and communicates with the nRF9160 serial modem over UART for Internet access. Switch back to NCS manifest, build and flash by changing the SWD switch (SW10) to nRF52, then:

west config manifest.file west-ncs.yml
west update
west patch apply
west build -p -b nrf9160dk/nrf52840 --sysbuild pouch-gateway/gateway/
west flash

MG100

Setup repo with Zephyr:

west init -m https://github.com/golioth/pouch-gateway.git --mf west-zephyr.yml
west update
west zephyr-export
pip install -r zephyr/scripts/requirements.txt

Gateway firmware runs on nRF52840 chip. There is direct access to LTE modem and also Bluetooth Host stack. Build and flash it with:

west build -p -b mg100 pouch-gateway/gateway --sysbuild
west flash

Useful options for debugging and development

Running gateway with simulator or USB dongle

See Running Pouch Gateway with simulator.

CONFIG_POUCH_GATEWAY_CLOUD

It is possible to disable communication with cloud, so that only Bluetooth part is tested. In context of nrf52_bsim this allows to run without BabbleSim handbrake, which normally slows down simulation to respect communication timeouts enforced in SDK. In case of cellular connected platforms (nRF91) there is no latency because of cellular network infrastructure.

CONFIG_POUCH_GATEWAY_CLOUD is available both on the gateway applicaton level (pouch-gateway/gateway) as well as in sysbuild (mainly for ease of use) as SB_CONFIG_POUCH_GATEWAY_CLOUD.

Running nrf52_bsim simulaton without cloud communication can be done with:

west build -p -b nrf52_bsim pouch-gateway/gateway --sysbuild -- \
  -DSB_CONFIG_POUCH_GATEWAY_CLOUD=n
west flash