Tools
HOME » RESOURCES » TOOLS » LoRa Basics Station » Configuration Files

LoRa Basics Station

Configuration Files

Station requires a configuration file named station.conf which contains settings for the configuration of Station itself and the configuration of the radio concentrator boards. If Station has been built to operate multiple v1.5 concentrator boards, additional configuration files slave-0.conf .. slave-N.conf MUST be present, where N+1 equals the number of concentrator boards available.

The basic layout of the file station.conf is shown below. In its most simple form the file MAY just contain {} with all settings falling back to their default values.

{
   "radio_conf": { .. }
   "station_conf": { .. }
}

All the fields of the station_conf are discussed in the following sections. The layout of the radio_conf object hereby depends on the type of concentrator design Station is built for. This is discussed in the Section Radio Configuration.

Logging Setup

Fields related to logging are as follows with their respective default values:

{
   "station_conf": {
     ...
     "log_file":    "~temp/station.log"
     "log_level":   "INFO"
     "log_size":    10e6
     "log_rotate":  3
   }
   ...
}

log_file specifies the path and filename of the main logfile. The default place ~temp/ is in a platform-specific directory, usually /var/tmp or /tmp.

log_level defines the level according to which messages are being logged. Messages less important than the specified level are suppressed. The value is a comma-separated sequence of one or more log definitions, whereby a log definition is a log level optionally prefixed with a module name and a colon.

Available log levels in increasing importance:

XDEBUG, DEBUG, VERBOSE, INFO, NOTICE, WARNING, ERROR, CRITICAL

Module names can be inferred from the log messages and are matched. For level names only the first four characters matter. The matching of both module names and level names is case-insensitive.

Example:

"log_level": "DEBUG,SYS:INFO,RAL:XDEBUG"

The log file will be filled up to a size of approximately log_size bytes. If the log file is full, it gets moved aside and a new and empty log file is started. log_rotate determines how many old log files are kept. If this has a value of N>0, additional old log files log_file.1, .., log_file.N will be present

The settings in the station.conf configuration file can be overwritten by environment variables or command line options. Command-line options supersede environment variables. The command station—help lists all command-line options and respective environment variable names.

The log level of a running Station can be changed using the FIFO file ~/cmd.fifo. If such a FIFO file does not yet exist, it MAY be created in the Station’s home directory (~/) next to the Station’s configuration files. The desired log level then MAY be written into the FIFO file as follows:

cd $STATION_HOME
mkfifo cmd.fifo
echo "DEBUG" > cmd.fifo

Station Identity

The identity of Station is a 64 bit number. This number uniquely identifies Station towards both LNS and CUPS. While this can be any number, the identity usually is a 64-bit EUI derived from the MAC of one of the network interfaces of the gateway.

The following two fields control the forming of an identity:

{
   "station_conf": {
     ...
     "routerid":    ID6 | EUI | MAC | "filename"
     "euiprefix":   ID6 | EUI
   }
   ...
}

If a routerid is set, it will be used. If a euiprefix option is set, it will be used as prefix when deriving the EUI64 identity (e.g., from the MAC address). This allows to individually control and separate single radio concentrator boards.

Time Synchronization Configuration

Station supports two different methods for time synchronization or transfer of GPS time: (1) With access to a PPS signal, and (2) independent of a PPS signal. Moreover, the PPS signal can come from hardware, or it can be simulated using software by means of a FIFO file. The corresponding configuration entry is as follows:

{
   "station_conf": {
     ...
     "gps": "DEVICEFILE" | "FIFO"
     "pps": "gps" | "fuzzy"
   }
}

If the pps option specifies gps, a PPS signal is expected which MUST be either coming from a hardware device or simulated from a file. If the pps option specifies fuzzy, a PPS signal is not required and the LNS computes the correspondence of GPS to concentrator ticks based on overlapping upstream packets.

Development/Debug Settings>

If Station is a development / debug build, the following fields can be used to tweak its behavior for testing purposes:

{
   "station_conf": {
     ...
     "nocca":   false
     "nodc":    false
     "nodwell": false
     PARAM: VALUE
   }
}

The fields nocca, nodc, and nodwell, if present and false, disable clear channel analysis (e.g., listen before talk), duty cycle, and dwell time limitations. PARAM holds internal configuration parameters that can be used to fine tune performance and resource consumption. The command station -p lists all those parameters.

Radio Configuration>

Station supports the concentrator reference designs v1.5 and v2. Currently, this decision is a compile-time option. The actual layout of the radio_conf field depends on the type of concentrator design supported and is discussed elsewhere (cf. Sections Concentrator Design v1.5 and Concentrator Design v2).

{
   "radio_conf": { .. }
   "station_conf": {
     ...
     "device":      "FILE" | "FILEPATTERN"
     "radio_init":  "FILE"
   }
}

The field device is just an alternate place to specify the path to the SPI device enabling access to the concentrator board. In case of multiple concentrator boards, the ‘?’ character MAY be used as a wildcard for the concentrator board index. The device can also be specified in the radio_conf object.

The field radio_init points to a file that is executed just before the concentrator boards are initialized. This initialization happens every time the Station connects to the LNS. This executable or script can toggle platform-specific GPIOs to reset the concentrator boards to ensure a consistent initial state. It is called with the SPI device path and optionally with the index of the concentrator board if multiple concentrator boards are configured.

These settings can be overridden by the environment variable STATION_RADIOINIT and the command-line option —radio-init.