LoRa Basics™ Station 2.0.5 documentation

Concentrator Design (v1.5)

LoRa Basics™ Station supports the concentrator reference design v1.5 as a compile-time option. The JSON configuration is very similar to what the Semtech Packet Forwarder accepts for the v1.5 design.

Support for the v1.5 design comes in two compile-time variants: (1) Single-board, and (2) Multi-board. The multi-board build may also handle a single board, of course, but it requires an additional configuration file (slave-0.conf) to do so.

Additionally, a Station can contain a statically-linked version of the lora_gateway library, so it can interact with the concentrator boards.

This topic lists the available object types and fields, with their possible values, as understood by a Station when parsing configuration files. The semantics of the fields are discussed in the documentation of each of the respective radio boards. Here, we briefly discuss only the additional fields or extensions specific to LoRa Basics Station.

A configuration need not specify any frequencies or enablement for IFCONF or RFCONF objects. This information is submitted by the LNS based on the channel plan assigned to a gateway. The channel-plan settings are merged with the local configuration before the concentrator board is initialized.

The concentrator configuration is embedded in the station.conf or slave-N.conf files in the following way:

{
  ...                    // possibly other fields e.g. "station_conf"
  "radio_conf"  : CONF
  "sx1301_conf" : CONF   // alias for radio_conf
  "SX1301_conf" : CONF   // alias for radio_conf
}

CONF Object

{
  "device"        : STRING   // station-specific
  "pps"           : BOOL     // station-specific
  "lorawan_public": BOOL
  "clksrc"        : INT
  "tx_gain_lut"   : [ TX_GAIN_LUT, .. ]
  "chan_FSK"      : IFCONF
  "chan_Lora_std" : IFCONF
  "chan_multiSF_X": IFCONF   // X in {0..7}
  "radio_0"       : RFCONF
  "radio_1"       : RFCONF
}

The device field specifies the SPI device that is used to communicate with the radio board. If multiple radio boards are used, the wildcard character (?) is replaced with the actual board index. The board index is inferred from the name of the slave configuration file slave-N.conf.

If the gateway has a PPS (from a GPS device or some other source), the concentrator board that has access to this signal must have the pps field set to true. One and only one board must have this field set to true.

Note

LoRa Basics Station does not require access to a GPS device to maintain a global GPS time for Class B operations. A PPS, aligned with the GPS time, is sufficient.

TX_GAIN_LUT Object

{
  "pa_gain" : INT[0..3]
  "dig_gain": INT[0..3]
  "dac_gain": INT[0..3]
  "mix_gain": INT[0..3]
  "rf_power": INT[-128..127]
}

All of the TX_GAIN_LUT fields are optional. If a field is missing, its value is read as zero.

RFCONF Object

{
  "enable"         : BOOL
  "tx_enable"      : BOOL
  "txpow_adjust"   : INT   // alias for antenna_gain
  "antenna_gain"   : INT
  "antenna_type"   : "omni" | "sector"    // station specific
  "freq"           : INT
  "tx_notch_freq"  : INT
  "rssi_offset"    : INT
  "rssi_offset_lbt": INT
  "type"           : "SX1255" | "SX1257" | "SX1272" | "SX1276"
}

All of the RFCONF fields are optional. Absent fields are read as false or zero. If antenna_type or type are absent, the value is undefined. Note that txpow_adjust is simply an alias for antenna_gain.

Station targets a specific output power to be dissipated. The values of the fields txpow_adjust and antenna_gain are subtracted from this target value to account for any gains by the antenna and any losses by the cable.

The antenna_type field specifies the nature of the antenna. The response to an uplink frame received via a sector antenna is always sent back over the same antenna. This is also the preferred behavior for an antenna labeled omni. If the antenna is blocked (for instance, due to duty-cycle limitations or being busy with another transmission), the Station may transfer the downlink transmission to another omni antenna.

IFCONF Object

{
  "enable"        : BOOL
  "radio"         : INT       // alias for rf_chain
  "rf_chain"      : INT
  "freq"          : INT
  "bandwidth"     : INT(125000,250000,500000)
  "spread_factor" : INT(7..12)
  "datarate"      : INT
  "sync_word"     : INT
  "sync_word_size": INT
}

Single-Board Sample Configuration

Here is a sample configuration for a single board:

 {
   ...
   "radio_conf": {                  /* Actual channel plan is controlled by the server */
       "lorawan_public": true,      /* is default */
       "clksrc": 1,                 /* radio_1 provides clock to concentrator */
       "device": "spidev",          /* default SPI device is platform specific */
       "radio_0": {
           /* freq/enable provided by LNS - only hardware-specific settings are listed here */
           "type": "SX1257",
           "rssi_offset": -166.0,
           "tx_enable": true,
           "antenna_gain": 0
       },
       "radio_1": {
           "type": "SX1257",
           "rssi_offset": -166.0,
           "tx_enable": false
       }
       /* chan_multiSF_X, chan_Lora_std, chan_FSK provided by LNS */
   }
   ...
}

The configuration contains only board-specific settings. All parameters related to a channel plan are omitted because they are provided by the LNS and merged on the fly.

Multi-Board Sample Configuration

The multi-board Station variant requires additional configuration files, slave-N.conf, for each board where N={0,1,..}. The settings of the radio_conf field are merged with station.conf and the fields in station.conf provide default values for the respective slave files.

Here is a sample configuration for two boards:

 {
   ...
   "radio_conf": {
       "clksrc": 1,                 /* radio_1 provides clock to concentrator */
       "device": "spidev?.0",       /* ? is replaced with the save index */
       "radio_0": {
           "rssi_offset": -166.0,
           "tx_enable": true,
           "antenna_gain": 0
           "antenna_type": "omni",
       },
       "radio_1": {
           "rssi_offset": -166.0,
           "tx_enable": false
       }
   }
   ...
}

Example of slave-0.conf, which overrides the antenna gain:

 {
   "SX1301_conf": {
       "radio_0": {
           "antenna_gain": 3.0
       }
   }
}

and an example of slave-1.conf, which reuses all values from station.conf:

{}

Note: The SPI device in station.conf contains a wildcard (?) which gets replaced by the slave index (0, 1, ..). In the example setup, the Station would access the devices /dev/spidev0.0 and `/dev/spidev1.0. If the SPI device paths of the different boards are not compatible with this wildcard scheme, the device name must be explicitly specified in each of the slave configuration files.