Quick Start

The following is a three-step quick start guide on how to build and run Station. It uses a Raspberry Pi with an IMST shield as target platform and builds on the target platform itself.

Step 1: Cloning the Station Repository

git clone https://github.com/lorabasics/basicstation.git

Step 2: Compiling the Station Binary

cd basicstation
make platform=rpi variant=std

Step 3: Running the Example Configuration

cd examples/live-s2.sm.tc
RADIODEV=/dev/spidev0.0 ../../build-rpi-std/bin/station

Note: The SPI device for the radio MAY be passed as an environment variable using RADIODEV.

The example configuration connects to a public test server s2.sm.tc through which Station fetches all required credentials and a channel plan matching the region as determined from the IP address of the gateway. Provided there are active LoRa devices in proximity, received LoRa frames are printed in the log output on stderr.

Below is the output of the invocation on a Kerlink gateway. Note: For Kerlink the RADIODEV environment vairable is set to /dev/spidev32766.0 as SPI device path.

[@Wirgrid_0b03044f live-s2.sm.tc]# RADIODEV=/dev/spidev32766.0 ./station
2018-11-09 10:25:49.004 [SYS:INFO] Logging     : stderr (maxsize=10000000, rotate=3)
2018-11-09 10:25:49.007 [SYS:INFO] Station Ver : TrackStation_2.0-484-g143c1fe(kerlink/std) 2018-11-08T15:24Z
2018-11-09 10:25:49.010 [SYS:INFO] Package Ver : 1.0.0
2018-11-09 10:25:49.012 [SYS:INFO] proto EUI   : 0:24b:b03:44f       (/sys/class/net/eth0/address)
2018-11-09 10:25:49.014 [SYS:INFO] prefix EUI  : ::1 (builtin)
2018-11-09 10:25:49.014 [SYS:INFO] Station EUI : 24b:bff:fe03:44f
2018-11-09 10:25:49.015 [SYS:INFO] Station home: ./  (builtin)
2018-11-09 10:25:49.015 [SYS:INFO] Station temp: /var/tmp/   (builtin)
2018-11-09 10:25:49.219 [TCE:INFO] Starting TC engine
2018-11-09 10:25:49.220 [TCE:ERRO] No TC URI configured
2018-11-09 10:25:49.221 [CUP:INFO] Starting a CUPS session
2018-11-09 10:25:49.221 [CUP:ERRO] No CUPS URI configured
2018-11-09 10:25:49.222 [TCE:INFO] INFOS reconnect backoff 0s (retry 0)
2018-11-09 10:25:49.224 [TCE:ERRO] No TC URI configured
2018-11-09 10:25:49.224 [TCE:INFO] INFOS reconnect backoff 10s (retry 1)
2018-11-09 10:25:50.222 [CUP:INFO] Starting a CUPS session
2018-11-09 10:25:50.223 [CUP:ERRO] No CUPS-bak URI configured
2018-11-09 10:25:51.223 [CUP:INFO] Starting a CUPS session
2018-11-09 10:25:51.224 [CUP:INFO] Connecting to CUPS-boot ... https://s2.sm.tc:7007 (try #3)
2018-11-09 10:25:51.251 [any:INFO] cert. version     : 1
serial number     : 0C
issuer name       : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
subject name      : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
issued  on        : 2018-11-08 12:42:00
expires on        : 2024-11-06 12:42:00
signed using      : ECDSA with SHA256
EC key size       : 256 bits
2018-11-09 10:25:51.329 [any:INFO] cert. version     : 3
serial number     : 10
issuer name       : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
subject name      : CN=gwprov-::0, OU=TrackCentral, O=TrackNet.io, C=CH
issued  on        : 2018-11-08 12:43:52
expires on        : 2020-11-07 12:43:52
signed using      : ECDSA with SHA256
RSA key size      : 2048 bits
2018-11-09 10:25:51.329 [AIO:INFO]
2018-11-09 10:25:51.391 [CUP:VERB] Retrieving update-info from CUPS-boot https://s2.sm.tc:7007...
2018-11-09 10:25:53.921 [CUP:INFO] CUPS URI updated: https://s2.sm.tc:7007
2018-11-09 10:25:53.925 [CUP:INFO] TC URI updated: wss://s2.sm.tc:7000
2018-11-09 10:25:53.925 [CUP:INFO] CUPS credentials segment (956 bytes)
2018-11-09 10:25:53.925 [any:INFO] credComplete - trust_off=   0, trust_len= 412            30 82 01 97  30 82 01 3c
2018-11-09 10:25:53.926 [any:INFO] credComplete - cert_off = 412, cert_len = 420  f4 e1 69 00  30 82 01 a0  30 82 01 46
2018-11-09 10:25:53.926 [any:INFO] credComplete - key_off  = 832, key_len  = 124  87 bc 92 de  30 77 02 01  01 04 20 9c
2018-11-09 10:25:53.937 [CUP:INFO] CUPS credentials updated (956 bytes)
2018-11-09 10:25:53.937 [CUP:INFO] TC credentials segment (956 bytes)
2018-11-09 10:25:53.937 [any:INFO] credComplete - trust_off=   0, trust_len= 412            30 82 01 97  30 82 01 3c
2018-11-09 10:25:53.937 [any:INFO] credComplete - cert_off = 412, cert_len = 420  f4 e1 69 00  30 82 01 a0  30 82 01 46
2018-11-09 10:25:53.938 [any:INFO] credComplete - key_off  = 832, key_len  = 124  87 bc 92 de  30 77 02 01  01 04 20 9c
2018-11-09 10:25:53.949 [CUP:INFO] TC credentials updated (956 bytes)
2018-11-09 10:25:53.968 [AIO:DEBU] [3] HTTP connection shutdown...
2018-11-09 10:25:53.971 [CUP:INFO] CUPS provided TC updates (uri) - restarting TC engine
2018-11-09 10:25:53.971 [TCE:INFO] Terminating TC engine
2018-11-09 10:25:53.972 [CUP:INFO] CUPS provided CUPS updates (uri) - reconnecting in 1s
2018-11-09 10:25:53.972 [TCE:INFO] Starting TC engine
2018-11-09 10:25:53.974 [any:INFO] cert. version     : 1
serial number     : 0C
issuer name       : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
subject name      : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
issued  on        : 2018-11-08 12:42:00
expires on        : 2024-11-06 12:42:00
signed using      : ECDSA with SHA256
EC key size       : 256 bits
2018-11-09 10:25:53.976 [any:INFO] cert. version     : 3
serial number     : 14
issuer name       : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
subject name      : CN=router-24b:bff:fe03:44f, OU=TrackCentral, O=TrackNet.io, C=CH
issued  on        : 2018-11-08 13:14:46
expires on        : 2020-11-07 13:14:46
signed using      : ECDSA with SHA256
EC key size       : 256 bits
2018-11-09 10:25:53.977 [AIO:INFO]
2018-11-09 10:25:54.020 [TCE:INFO] Connecting to INFOS: wss://s2.sm.tc:7000
2018-11-09 10:25:54.842 [TCE:INFO] Infos: router-24b:bff:fe03:44f muxs-::0 wss://s2.sm.tc:7001/router-24b:bff:fe03:44f
2018-11-09 10:25:54.843 [AIO:DEBU] [3] ws_close reason=1000
2018-11-09 10:25:54.844 [AIO:DEBU] [3] Server sent close: reason=1000
2018-11-09 10:25:54.844 [AIO:DEBU] [3] WS connection shutdown...
2018-11-09 10:25:54.847 [any:INFO] cert. version     : 1
serial number     : 0C
issuer name       : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
subject name      : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
issued  on        : 2018-11-08 12:42:00
expires on        : 2024-11-06 12:42:00
signed using      : ECDSA with SHA256
EC key size       : 256 bits
2018-11-09 10:25:54.849 [any:INFO] cert. version     : 3
serial number     : 14
issuer name       : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
subject name      : CN=router-24b:bff:fe03:44f, OU=TrackCentral, O=TrackNet.io, C=CH
issued  on        : 2018-11-08 13:14:46
expires on        : 2020-11-07 13:14:46
signed using      : ECDSA with SHA256
EC key size       : 256 bits
2018-11-09 10:25:54.849 [AIO:INFO]
2018-11-09 10:25:54.893 [TCE:VERB] Connecting to MUXS...
2018-11-09 10:25:55.809 [CUP:INFO] Starting a CUPS session
2018-11-09 10:25:55.810 [CUP:INFO] Connecting to CUPS ... https://s2.sm.tc:7007 (try #1)
2018-11-09 10:25:55.812 [any:INFO] cert. version     : 1
serial number     : 0C
issuer name       : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
subject name      : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
issued  on        : 2018-11-08 12:42:00
expires on        : 2024-11-06 12:42:00
signed using      : ECDSA with SHA256
EC key size       : 256 bits
2018-11-09 10:25:55.814 [any:INFO] cert. version     : 3
serial number     : 14
issuer name       : CN=Root CA, OU=TrackCentral (eiaPoUc9), O=TrackNet.io, C=CH
subject name      : CN=router-24b:bff:fe03:44f, OU=TrackCentral, O=TrackNet.io, C=CH
issued  on        : 2018-11-08 13:14:46
expires on        : 2020-11-07 13:14:46
signed using      : ECDSA with SHA256
EC key size       : 256 bits
2018-11-09 10:25:55.814 [AIO:INFO]
2018-11-09 10:25:55.858 [CUP:VERB] Retrieving update-info from CUPS https://s2.sm.tc:7007...
2018-11-09 10:25:57.092 [TCE:VERB] Connected to MUXS.
2018-11-09 10:25:57.117 [S2E:WARN] Unknown field in router_config - ignored: regionid (0xE6FFB211)
2018-11-09 10:25:57.117 [S2E:WARN] Unknown field in router_config - ignored: upchannels (0x7FCAA9EB)
2018-11-09 10:25:57.118 [S2E:WARN] Unknown field in router_config - ignored: config (0xF7A3E35F)
2018-11-09 10:25:57.118 [S2E:WARN] Unknown field in router_config - ignored: protocol (0xFD309030)
2018-11-09 10:25:57.118 [S2E:WARN] Unknown field in router_config - ignored: bcning (0x1EE5E245)
2018-11-09 10:25:55.985 [RAL:INFO] Lora gateway library version: Version: 5.0.1;
2018-11-09 10:25:55.985 [RAL:DEBU] SX1301 txlut table (0 entries)
2018-11-09 10:25:55.985 [RAL:VERB] SX1301 rxrfchain 0: enable=1 freq=868300000 rssi_offset=-166.000000 type=2 tx_enable=1 tx_notch_freq=0
2018-11-09 10:25:55.986 [RAL:VERB] SX1301 rxrfchain 1: enable=0 freq=0 rssi_offset=-166.000000 type=2 tx_enable=0 tx_notch_freq=0
2018-11-09 10:25:55.986 [RAL:VERB] SX1301 ifchain  0: enable=1 rf_chain=0 freq=-200000 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.987 [RAL:VERB] SX1301 ifchain  1: enable=1 rf_chain=0 freq=0 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.987 [RAL:VERB] SX1301 ifchain  2: enable=1 rf_chain=0 freq=200000 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.987 [RAL:VERB] SX1301 ifchain  3: enable=0 rf_chain=0 freq=0 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.987 [RAL:VERB] SX1301 ifchain  4: enable=0 rf_chain=0 freq=0 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.988 [RAL:VERB] SX1301 ifchain  5: enable=0 rf_chain=0 freq=0 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.988 [RAL:VERB] SX1301 ifchain  6: enable=0 rf_chain=0 freq=0 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.988 [RAL:VERB] SX1301 ifchain  7: enable=0 rf_chain=0 freq=0 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.988 [RAL:VERB] SX1301 ifchain  8: enable=0 rf_chain=0 freq=0 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.988 [RAL:VERB] SX1301 ifchain  9: enable=0 rf_chain=0 freq=0 bandwidth=0 datarate=0 sync_word=0/0
2018-11-09 10:25:55.989 [RAL:VERB] SX1301 LBT not enabled
2018-11-09 10:25:55.989 [RAL:INFO] Station device: /dev/spidev32766.0 (PPS capture disabled)
2018-11-09 10:25:58.907 [S2E:INFO] Configuring for region: EU863 -- 863.0MHz..870.0MHz
2018-11-09 10:25:58.907 [S2E:VERB]   DR0  SF12/BW125
2018-11-09 10:25:58.908 [S2E:VERB]   DR1  SF11/BW125
2018-11-09 10:25:58.908 [S2E:VERB]   DR2  SF10/BW125
2018-11-09 10:25:58.908 [S2E:VERB]   DR3  SF9/BW125
2018-11-09 10:25:58.908 [S2E:VERB]   DR4  SF8/BW125
2018-11-09 10:25:58.908 [S2E:VERB]   DR5  SF7/BW125
2018-11-09 10:25:58.908 [S2E:VERB]   DR6  SF7/BW250
2018-11-09 10:25:58.909 [S2E:VERB]   DR7  FSK
2018-11-09 10:25:58.909 [S2E:VERB]   DR8  undefined
2018-11-09 10:25:58.909 [S2E:VERB]   DR9  undefined
2018-11-09 10:25:58.909 [S2E:VERB]   DR10 undefined
2018-11-09 10:25:58.909 [S2E:VERB]   DR11 undefined
2018-11-09 10:25:58.910 [S2E:VERB]   DR12 undefined
2018-11-09 10:25:58.910 [S2E:VERB]   DR13 undefined
2018-11-09 10:25:58.910 [S2E:VERB]   DR14 undefined
2018-11-09 10:25:58.910 [S2E:VERB]   DR15 undefined
2018-11-09 10:25:58.910 [S2E:VERB]   TX power: 16.0 dBm EIRP
2018-11-09 10:25:58.910 [S2E:VERB]             27.0 dBm EIRP for 869.4MHz..869.65MHz
2018-11-09 10:25:58.911 [S2E:VERB]   JoinEui list: 0 entries
2018-11-09 10:25:58.911 [S2E:VERB]   NetID filter: FFFFFFFF-FFFFFFFF-FFFFFFFF-FFFFFFFF
2018-11-09 10:25:58.911 [S2E:VERB]   Dev/test settings: nocca=0 nodc=1 nodwell=0
2018-11-09 10:25:59.840 [AIO:DEBU] [4] HTTP connection shutdown...
2018-11-09 10:25:59.843 [CUP:INFO] Interaction with CUPS done (no updates) - next regular check in 1d
2018-11-09 10:26:40.932 [SYN:INFO] MCU/SX1301 drift stats: min: 0.0ppm  q50: -3.3ppm  q80: 6.7ppm  max: -90.4ppm - threshold q90: -8.6ppm
2018-11-09 10:26:40.933 [SYN:INFO] Avg MCU drift vs SX1301#0: 1.0ppm
2018-11-09 10:26:55.637 [SYN:INFO] Time sync qualities: min=108 q90=184 max=665 (previous q90=2147483647)
2018-11-09 10:27:00.889 [SYN:VERB] Time sync rejected: quality=244 threshold=184
2018-11-09 10:27:13.514 [SYN:VERB] Time sync rejected: quality=228 threshold=184
2018-11-09 10:27:15.615 [SYN:VERB] Time sync rejected: quality=235 threshold=184
2018-11-09 10:27:19.816 [SYN:VERB] Time sync rejected: quality=239 threshold=184
2018-11-09 10:27:26.118 [SYN:INFO] MCU/SX1301 drift stats: min: 0.5ppm  q50: 4.8ppm  q80: 10.5ppm  max: 10.9ppm - threshold q90: -10.9ppm
2018-11-09 10:27:26.118 [SYN:INFO] Avg MCU drift vs SX1301#0: 1.0ppm
2018-11-09 10:27:34.520 [SYN:VERB] Time sync rejected: quality=227 threshold=184
2018-11-09 10:27:36.621 [SYN:VERB] Time sync rejected: quality=232 threshold=184
2018-11-09 10:27:38.722 [SYN:VERB] Time sync rejected: quality=230 threshold=184
2018-11-09 10:27:56.576 [SYN:INFO] Time sync qualities: min=132 q90=235 max=244 (previous q90=184)
2018-11-09 10:28:07.079 [SYN:VERB] Time sync rejected: quality=258 threshold=235
2018-11-09 10:28:11.282 [SYN:VERB] Time sync rejected: quality=244 threshold=235
2018-11-09 10:28:14.838 [S2E:VERB] RX 868.1MHz DR5 SF7/BW125 snr=9.8 rssi=-63 xtime=0x290000083EAD83 - updf mhdr=40 DevAddr=3634B654 FCtrl=80 FCnt=3865 FOpts=[] 9320EB48..C977 mic=71511833 (24 bytes)
2018-11-09 10:28:15.483 [SYN:INFO] MCU/SX1301 drift stats: min: 0.0ppm  q50: -2.3ppm  q80: -10.5ppm  max: 17.6ppm - threshold q90: -13.8ppm
2018-11-09 10:28:15.484 [SYN:INFO] Avg MCU drift vs SX1301#0: 1.0ppm
2018-11-09 10:28:24.936 [SYN:VERB] Time sync rejected: quality=237 threshold=235
2018-11-09 10:28:35.439 [SYN:VERB] Time sync rejected: quality=253 threshold=235
2018-11-09 10:32:32.208 [S2E:VERB] RX 868.3MHz DR5 SF7/BW125 snr=7.8 rssi=-77 xtime=0x2900001795C233 - updf mhdr=40 DevAddr=0124504D FCtrl=80 FCnt=22225 FOpts=[] 660BB08A..881B mic=1015568105 (21 bytes)

Next Steps

Next, consult the help menu of the Station binary and inspect the station.conf and cups-boot.* example configuration files.

Built-in Help Menu

The Station binary accepts the following command-line options:

./station --help
Usage: station [OPTION...]

  -d, --daemon               First check if another process is still alive. If
                             so do nothing and exit. Otherwise fork a worker
                             process to operate the radios and network
                             protocols. If the subprocess died respawn it with
                             an appropriate back off.
  -f, --force                If a station process is already running, kill it
                             before continuing with requested operation mode.
  -h, --home=DIR             Home directory for configuration files. Default is
                             the current working directory. Overrides
                             environment STATION_DIR.
  -i, --radio-init=cmd       Program/script to run before reinitializing radio
                             hardware. By default nothing is being executed.
                             Overrides environment STATION_RADIOINIT.
  -k, --kill                 Kill a currently running station process.
  -l, --log-level=LVL|0..7   Set a log level LVL=#loglvls# or use a numeric
                             value. Overrides environment STATION_LOGLEVEL.
  -L, --log-file=FILE[,SIZE[,ROT]]
                             Write log entries to FILE. If FILE is '-' then
                             write to stderr. Optionally followed by a max file
                             SIZE and a number of rotation files. If ROT is 0
                             then keep only FILE. If ROT is 1 then keep one
                             more old log file around. Overrides environment
                             STATION_LOGFILE.
  -N, --no-tc                Do not connect to a LNS. Only run CUPS
                             functionality.
  -p, --params               Print current parameter settings.
  -t, --temp=DIR             Temp directory for frequently written files.
                             Default is /tmp. Overrides environment
                             STATION_TEMPDIR.
  -x, --eui-prefix=id6       Turn MAC address into EUI by adding this prefix.
                             If the argument has value ff:fe00:0 then the EUI
                             is formed by inserting FFFE in the middle. If
                             absent use MAC or routerid as is. Overrides
                             environment STATION_EUIPREFIX.
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -v, --version              Print station version.

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

Example Configuration

The minimal required configuration for retrieving credentials and the URI of the LNS are the bootstrap credentials and bootstrap URI as described in Section Files Related to Station.

For the s2.sm.tc example test server, these are as follows:

cat cups-boot.uri
 https://s2.sm.tc:7007

cat cups-boot.crt
 -----BEGIN CERTIFICATE-----
 MIIBkzCCATmgAwIBAgIBQTAKBggqhkjOPQQDAjBXMRAwDgYDVQQDDAdSb290IENB
 MSAwHgYDVQQLDBdUcmFja0NlbnRyYWwgKGVpYVBvVWM5KTEUMBIGA1UECgwLVHJh
 Y2tOZXQuaW8xCzAJBgNVBAYTAkNIMB4XDTE5MDMwNzE1MjgwNVoXDTIxMDMwNjE1
 MjgwNVowTzETMBEGA1UEAwwKZ3dwcm92LTo6MDEVMBMGA1UECwwMVHJhY2tDZW50
 cmFsMRQwEgYDVQQKDAtUcmFja05ldC5pbzELMAkGA1UEBhMCQ0gwWTATBgcqhkjO
 PQIBBggqhkjOPQMBBwNCAASFyfmqBPkza9kd2IkrbU3zSRIriq5vOcgwfilctZVs
 j8Z7XVBMdNLjriSjchVgyBTJfvMVMbvYTdzD7w5GBSNwMAoGCCqGSM49BAMCA0gA
 MEUCIQCFGgSlP6GYM6uXd6KXuEwc098p5orHP/dxupGAZifquwIgbUh9UAR8tgAi
 8TH36s9z+mz27ea7ezcmH8aM4W3Meng=
 -----END CERTIFICATE-----

cat cups-boot.key
 -----BEGIN EC PRIVATE KEY-----
 MHcCAQEEIJbt0pUj24UIWS6HngUqJtP3uPpweSIqhB4TRoyHdzdqoAoGCCqGSM49
 AwEHoUQDQgAEhcn5qgT5M2vZHdiJK21N80kSK4qubznIMH4pXLWVbI/Ge11QTHTS
 464ko3IVYMgUyX7zFTG72E3cw+8ORgUjcA==
 -----END EC PRIVATE KEY-----

The station.conf configuration file contains the minimal set of parameters required for configuring and starting the SX1301. The actual channel plan configuration is received from the LNS, as mentioned before.

Example configuration:

{
    /* If slave-X.conf present this acts as default settings */
    "SX1301_conf": {              /* Actual channel plan is controlled by server */
        "lorawan_public": true,      /* is default */
        "clksrc": 1,              /* radio_1 provides clock to concentrator */
        /* path to the SPI device, un-comment if not specified on the command line e.g., RADIODEV=/dev/spidev0.0 */
        /*"device": "/dev/spidev0.0",*/
        /* freq/enable provided by LNS - only HW specific settings listed here */
        "radio_0": {
            "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 */
    },
    "station_conf": {
        "log_file":  "stderr",
        "log_level": "DEBUG",  /* XDEBUG,DEBUG,VERBOSE,INFO,NOTICE,WARNING,ERROR,CRITICAL */
        "log_size":  10000000,
        "log_rotate":  3
    }
}