Skip to content

Integration Guide

Overview

This integration guide explains how a miro EdgeCard can be integrated with any linux system offering a mPCIe slot. This guide is valid for the following miro EdgeCards

  • miro EdgeCard 08 EU868 and US915 (based on SX1308)
  • miro EdgeCard 02 EU868 and US915 (based on SX1302)
  • miro EdgeCard 2G4

Block Schematics

Theory of operation

The miro EdgeCard implements a standard ACM device (virtual serial character device) for communication with the host. The Linux driver needed is cdc_acm. The software stack on the host side, as provided by Semtech and modified by Miromico, consists of two parts:

  • the HAL library provides a generic way to access the hardware
  • the packet forwarder using the HAL, which implements a simple protocol to forward radio packets to a server (and vice versa).
  • Some LoRaWAN network stacks implement their own custom packet forwarder or have a local daemon running to which the packet forwarder connects to. The intention is to mitigate the shortcomings of the Semtech packet forwarder (such as problems with NAT traversal). Hence, it is often referred to as "legacy packet forwarder".

Initial operation

A first system check should be done with lsusb or /sys/kernel/debug/usb/devices etc. to check for a matching device on the USB bus:

lsusb
...
Bus 001 Device 004: ID 0483:5740 Miromico EDGE-GWC-02-LW-868
...

The device description reported by the linux system obviously depends on the actual card type.

A linux device such as /dev/ttyACMx should have been created.

Steps for integration

Once the card is detected by the linux system, the following steps are needed to complete the integration.

  1. (Cross)compile LoRa packet forwarder and tools for your target system
  2. Integrate binaries
  3. Modify packet forwarder configuration
  4. Create startup scripts

Source code

Get the source code relevant for the card you want to integrate. There are different repositories for SX1308, SX1302 and 2.4 ghz miro EdgeCards. See download section.

Build

The source code for integration consists of a HAL library the packet forwarder and a set of tools. The HAL layer is built as a static library, and then statically linked into the packet forwarder. All components have their own Makefile, but can be built in one go using the top-level Makefile. Check the Makefile and make sure to set all variables such as \((CROSS_COMPILE)_ or _\)(ARC), etc. to match your compiler and target architecture.

Note

Some linux distributions are using different libc (e.g. OpenWRT is based on libmusl). There are some incompatiblies among those libraries, which might need some slight modifications of the source code.

Integration of Binaries

At least the packet forwarder needs to be integrated into the target system. It is recommended to also integrate the other tools, as they might become handy for configuration and diagnosis. Simply copy all needed binaries to the target system or integrate them as per build system used for your application.

Packt Forwarder Configuration

The forwarder has a single configuration file, global_conf.json, which specifies, among others:

  • USB device assigned to the card
  • gateway id, a "unique" 8-Byte number to identify the gateway. This is usually derived from the device's MAC address
  • Center frequencies of the two radio frontends
  • Frequency difference to the actual frequency for each receive channel
  • LNS host name and port

The software repository holds some example config files.

Startup Script

To have your system working as a standalone LoRaWAN gateway, the packet forwarder needs to be started on system startup. This depends on the actual linux distribution running on the target system.

Example call for global_conf.json in /opt and the gateway card on /dev/ttyACM1 (defaults are /dev/ttyACM0 and the current path for the config file):

lora_pkt_fwd -d /dev/ttyACM1 -c /opt

In-System Firmware Update

In order to update or install miro EdgeCard firmware, the on-board (ROM) bootloader of the integrated MCU is exposed over the interface.

Update Schematic

Current firmware images are available for download.

DFU Bootloader

To update the firmware, the MCU on the card has to be put into DFU bootloader mode. This can be done by toggling RST pin while BOOT pin his held high. See sample script for more details.

Important

NRST needs to be connected to a GPIO of the host MCU in order to trigger the update process. Do not connect NRST to the global reset network

If hardware pins are not accessible or not connected to the mPCIe interface, there is a software command to bring the card DFU mode. util_boot.c is implementing this command and will bring the card into DFU mode. Just compile it for your platform. On miro Edge devices, this utility is already preinstalled at /opt/util_boot.

Update Procedure

The ROM bootloader of the STM MCU integrated with the miro EdgeCard is implementing a DFU protocol over USB DFU class. Detail procedure und protocol is documented in STMicroelectronics AN3156 Application note.

To initiate the firmware update process, the BOOT pin (pin 19) has to be held high while applying a reset pulse to the card on the NRST pin (pin 22). This will force the MCU into bootloader mode, and the card will re-enumerate on the USB bus as a DFU device.

DFU Utility

There is a DFU utility tool available for download. dfu-util is a host side implementation of the DFU 1.0 and DFU 1.1 specifications of the USB forum. DFU is intended to download and upload firmware to/from devices connected over USB.

With any given firmware file in dfu format, the update can then be applied with

dfu-util -a 0 -D  <file.dfu>

See sample script for an example on how to update the firmware. On the miro Edge devices, this script is preinstalled at /opt/flash_gwcard_dfu.sh.

After a successful firmware update, the card needs to be reset while BOOT pin is held low to start normal operation. For normal operation BOOT pin has to be held low during reset and power up.

If hardware pins are not accessible or not connected to the interface, the system needs to be power cycled or run the following command to start the new firmware in the MCU

dfu-util -a 0 -s 0x08000000:leave

Antenna Selection

All miro EdgeCards provide the feature to use internal or external antenna. Antenna selection is implemented using an RF switch. Antennas can be switched during operation using a specific tool provided with the integration software.

For SX1308 based cards use util_settings

util_settings -d /dev/ttyACMx -w <ant>,1,1

For SX1302 based cards use ant_sel

ant_sel -d /dev/ttyACMx -a <ant>

In both cases <ant> is 0 for internal antenna, and 1 for external antenna. /dev/ttyACMx has to point to the actual USB devices assigned to the card.

Important

Antenna selection has to be configured after each card reset (e.g. power cycle).

Miromico additions to the Semtech provided sources

For the HAL and packet forwarder, Miromico integrated some additional features on top of the official release from Semtech:

  • SLIP encoding of the characters over the (virtual) serial line to prevent synchronization loss (SX1308)
  • additional commands to configure the RF frontend and switch the antenna path (internal/external antenna), depending on the specific hardware version (all cards)
  • Some adaptions to work with libmusl on OpenWRT (all cards)