Skip to content

Integration Guide

Overview

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

  • miro EdgeCard GWC-02 EU868 and US915 (based on SX1302)
  • miro EdgeCard GWC-08 EU868 and US915 (based on SX1308)
  • miro EdgeCard 80 (2.4 GHz)

GWC-08 is end of life

Use miro EdgeCard GWC-02 for new designs.

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 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 the downloads page.

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 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 use a different libc (e.g. OpenWRT is based on libmusl). There are some incompatibilities among those libraries, which might require 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 may be useful for configuration and diagnosis. Simply copy all needed binaries to the target system or integrate them as per the build system used for your application.

Packet 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, 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 the RST pin while the BOOT pin is held high. See the sample script for more details.

Important

NRST needs to be connected to a GPIO of the host MCU 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 into DFU mode. util_boot.c implements 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 implements a DFU protocol over USB DFU class. The detailed procedure and protocol is documented in the 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 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 the BOOT pin is held low to start normal operation. For normal operation the 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 Recommendation

The miro EdgeCard has been certified using the 2JW1115-C952B 868/915 MHz ISM antenna from 2J Antennas. This antenna is ground-plane independent and suitable for enclosure mounting without a metal backplane.

The card exposes a U.FL connector. Connect the antenna using a U.FL to SMA adapter cable.

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)