User Configuration Guide for `user.cfg`

The user.cfg file is used to configure various settings for the RockBLOCK Pro. This configuration file allows users to control settings related to serial communication, I/O options, and position reports. It can be updated via mass storage over Type-C, over AT serial commands, over Cloudloop Device Manager and over RockCONNECT IoT Bluetooth app. Below is a description of the fields and how users can customise them to suit their needs.

Further details and instructions for transferring the configuration file to the Pro can be found here: Firmware and Config Update Process

The User Configuration will be retained following a FW update - although it is recommended to check the new user.cfg for any additions or changes.

important

It is recommended to use a JSON editor when changing the file as invalid JSON will revert to the default User Configuration file with no error reported.

Serial Communication

The Serial section configures serial communication settings for the Pro AT interface.

mode: Serial communication mode such as RS232, RS4XX_FULL, RS4XX_HALF
baud: Baud rate for serial communication (4800, 9600, 19200 , 38400, 57600, 115200 (Default), 230400).
parity: Parity setting for serial communication, such as NONE. (EVEN and ODD are not implemented currently).
bits: Number of data bits (typically 8).
stop: Number of stop bits (1 or 2).

BLE Configuration

The BLE section has the following options

Enabled: set true to enable (BLE module powered on) or false to disable (BLE module powered off).
connectionTimeout: Length of time in seconds that a connection will be maintained for with no BLE activity. (Min=60, Max=3600)

GNSS Configuration (Shared with APNT)

info

Note: All units are shipped with nmeaForwardEnabled set to false.

GNSS: Configures whether the use of the builtin receiver is enabled or disabled.
- true to enable, false to disable. See Enabled.
nmeaForwardEnabled: When set to true transforms the Physical Serial port into an NMEA sentences streaming port (VCP can still be used as an AT interface port), false disables the NMEA Forwarding. See NMEA forwarding.
reportInterval: Sets the regular IMT position reporting in seconds to Cloudloop Device Manager and Cloudloop Tracking, 0 (zero) disables the regular position reporting. See Report interval.
apntMode: Sets the APNT Mode, such as STATIC, DYNAMIC or AUTO. See APNT mode.
apntKalmanFilter: Sets the Kalman filter to MARITIME, WALKING, DRIVING or CUSTOM if apntMode is DYNAMIC. See APNT Kalman filter.
customVtc, customHtc, customVss, customHss: Custom Kalman filter values, used when apntKalmanFilter is CUSTOM. See Custom Kalman Filter settings
apntSensitivity: Sets the APNT Sensitivity, such as LOW, MED or HIGH. See APNT RF sensitivity.
apntPowerSaving: Sets the APNT Power Saving to FAST or ECO. See APNT power saving.
nmeaSentences: Toggles individual NMEA sentences to be shown or not. See NMEA sentence selection and Position output.
- "GNGGA": - set true to enable or false to disable
- "GNRMC": - set true to enable or false to disable
- "GPGGA": - set true to enable or false to disable
- "GPRMC": - set true to enable or false to disable
- "GPZDA": - set true to enable or false to disable
- "PJLTPOS": - set true to enable or false to disable
- "PJLTSTAT": - set true to enable or false to disable
- "PJLTSVI": - set true to enable or false to disable
- "PJLTVEL": - set true to enable or false to disable
- "AISVDO": - set true to enable or false to disable
apntFilterPosition: When set to true the position report will use the APNT position that has the lowest EPE from the last 20% of the set report interval. i.e. If set to 10min it will select the best from the last 2min. The reported GNSS timestamp will match APNT. Set to false to report without the filter applied. Available from FW version 0.19. See APNT filter position.
apntHot When false and the reporting period is longer than 30 minutes the APNT module remains unpowered until 20 minutes before a fix is due. When set to true the APNT module remains powered at all times. See APNT hot.
apntPositionSource: Sets the PNT module to output GNSS or APNT positions. See APNT positioning source.
compactReport When true the unit transmits a compact version of the location report into the Cloudloop platform. This reduces the report size from 132 Bytes to the minimum IMT(9704) billing increment of 25 Bytes. When false standard position reporting will be used.
compactReportOptions Option selection not currently supported in firmware v0.21. All are set to true by default.
- compactLocationV1
- "altitude" : - set 'true' to include an altitude value in the compact report. Firmware v0.21 ignores the setting.
- "power" : - set 'true' to include a power value in the compact report. Firmware v0.21 ignores the setting.
- "temperature" : - set 'true' to include a temperature value in the compact report. Firmware v0.21 ignores the setting.

Example GNSS section showing every APNT setting (not the shipped configuration):

  "GNSS": {
    "Enabled": true,
    "nmeaForwardEnabled": true,
    "reportInterval": 900,
    "apntMode": "DYNAMIC",
    "apntKalmanFilter": "MARITIME",
    "apntSensitivity": "HIGH",
    "customVtc": 5,
    "customHtc": 60,
    "customVss": 0.1,
    "customHss": 15,
    "apntPowerSaving": "FAST",
    "nmeaSentences": {
      "GNGGA": false,
      "GNRMC": false,
      "GPGGA": true,
      "GPRMC": true,
      "GPZDA": false,
      "PJLTPOS": false,
      "PJLTSTAT": false,
      "PJLTSVI": false,
      "PJLTVEL": false,
      "AISVDO": true
    },
    "apntFilterPosition": true,
    "apntHot": false,
    "apntPositionSource": "APNT"
  }

info

For more information on APNT please refer to our APNT (Iridium STL®) page

Sensors

Enabled: set true to enable on board temperature sensing or false to disable.

JAMMING and SPOOFING detection and display settings.

These settings enable configuration of the Jamming and Spoofing alarm trigger conditions as well as the displayed graphics. The boundary for spoof detection always scales with the APNT Estimated Position Error (EPE) so that changes in the level of this error do not cause false alarms.

Alarm Suppression is ONLY possible by parameter adjustment. It is clear that if false positives are occurring or if the alarm is triggering too often then adjustment of the parameters below can reduce annoyance and tune the sensitivity to an appropriate level.

"Chart": Allows the plotting of positions on a compatible chart plotter (i.e Raymarine AXIOM® 9)
- "epeScale": - Multiplier that sets the boundary (second circle) for tripping the SPOOF detection alarm, set from 0.5 - 10.0
- "positionCompareTimer": - Time the GNSS position needs to be outside the boundary(epescale * epe) before the SPOOF detection alarm is triggered, set from 0 - 300 seconds.
- "utcDifferenceLimit": - Affects the threshold before time spoof checking starts the timer, set from 2 - 10 seconds
- "utcDifferenceTimer": - Affects the amount of time the time difference threshold needs to be exceeded before alarming, set from 0 - 300 seconds.
- "positionValidityTimer": - Affects the amount of time GNSS fixes are INVALID or JAMMED before alarming, set from 0 - 300 seconds.
- "errorCircle": - Enables or disables the display of the APNT Estimated Position Error (inner circle), set true to display or false to hide.
- "errorLimitCircle": - Enables or disables the display of the outer circle, set true to display or false to hide.
- "testingAllowed": - set true to enable the Connect IoT app to impose GNSS position changes for local test and demonstration purposes. Set false to disable.

Example Chart section, as in the v0.29 factory default user.fac:

  "Chart": {
    "epeScale": 1.0,
    "positionCompareTimer": 0,
    "utcDifferenceLimit": 3,
    "utcDifferenceTimer": 0,
    "positionValidityTimer": 0,
    "errorCircle": false,
    "errorLimitCircle": false,
    "testingAllowed": false,
    "alarmLimit": 1800
  }

info

For more information on the APNT Chart Plotter please refer to here

IO Configuration (GPIO)

important

Requires FWv0.19+.

The IO section allows for configuration of I/O options.

IOtype: Defines the type of I/O. Options are NONE, DIGITAL or UNIVERSAL(Not yet implemented). In power constrained systems that do not need IO 'NONE' will reduce power consumption.
IOChans:
- channelIndex e.g. 1, 2, 3, 4, The channel number.
- channelMode:
  - "NONE": Channel disabled.
  - "digitalInput": - Standard input. Can be configured to provide a periodic value reading via IMT MO.
  - "digitalOutput": - Channel will operate as an output (open drain) controlled via IMT MO message.
  - "digitalInIntRising": - Will send an immediate(dependent on filter) value reading on rising edge. Can also report periodically.
  - "digitalInIntFalling": - Will send an immediate(dependent on filter) value reading on falling edge. Can also report periodically.
  - "digitalInIntChange": - Will send an immediate(dependent on filter) value reading on both rising and falling edge. Can also report periodically.
  - "digitalOutConfirmed": - Acknowledgement of output drive will be provided as IMT MT message.
- filter: - Sets the digital input sensitivity level. i.e. the number of milliseconds that the input will need to be stable for after change.
  - "LOW": - 200 milliseconds.
  - "MEDIUM": - 100 milliseconds.
  - "HIGH": - 50 milliseconds.
- hystersis: - Hysteresis can be set to prevent multiple triggers at the threshold. default is 0.1 volts.
- threshold: - Digital inputs can be given varying thresholds. Default is 1.5 volts.
- reportCoV: - Default 0.0 NOTE the analogue input Change of Value function is not yet implemented.
- reportPeriod: - Sets the period (In seconds) between each input report. '0' turns periodic reporting off. Default 0

Sleep Mode

The SleepMode section configures the Pro's external sleep pin behaviour.

SleepMode: Defines the state of the sleep mode.
- NONE disables the use of Sleep Pin.
- SleepModeB enables the use of Sleep Pin.
- Refer to Power Connection Options on how to activate sleep.

IMT Configuration

The IMT section handles the IMT (Iridium Messaging Transport topic) configuration.

defaultTopic: Sets the default IMT topic (e.g. 244 a.k.a RAW IMT Topic).
defaultTTL: Sets the default Time to Live (TTL) in seconds for IMT messages (e.g. 86400 = 1 day before a message expires).
serialRelayTopic: Set to 0. NOT CURRENTLY USED. Placeholder for planned future features.
startupEventEnabled: Toggles the Startup Events sent to Cloudloop (e.g. false disables them and true enables them)

Buzzer configuration. NOT CURRENTLY IMPLEMENTED

The BUZZER section is reserved for future implementation of the internal buzzer feature.

Enabled: true or false No functional difference as the feature is not implemented.

SVI Configuration. RESERVED FOR INTERNAL TEST USE

When necessary it is possible to obtain regular reports containing various additional sentences related to APNT.

danger

Changing these settings could lead to VERY high level of data consumption.

reportDuration: Must be Set to 0 to disable.
reportTopic: INTERNAL TEST USE
reportInterval: INTERNAL TEST USE

Example SVI section, as in the v0.29 factory default user.fac:

  "SVI": {
    "reportDuration": 0,
    "reportTopic": 313,
    "reportInterval": 0
  }

See SVI reports.

Reducing power consumption.

To get the most optimal power consumption for your solution you can edit the User Configuration File to turn off features you won't be using.

Note that for APNT variants there are additional power saving configuration settings detailed in the GNSS section above.

danger

Tread carefully as disabling some features might mean losing access to your device!

Serial
- Can be turned off by disabling it in the User Configuration File
  - "Serial": { "Enabled": false, …

warning

By disabling Serial, the Pro will not be reachable through Serial and you will need to drop a new User Configuration File via Type-C or update Over the Air via Cloudloop Device Manager

LEDS
- Can be turned off in the User Configuration File
  - "LEDS": { "Enabled": false, …
BLE
- Can be turned off in the User Configuration File (Not currently implemented so OFF by default)
  - "BLE": { "Enabled": false, …
GNSS
- Can be turned off in the User Configuration File
  - "GNSS": { "Enabled": false, …

important

By disabling GNSS, the coordinates will have to be set manually by using the AT Serial Commands

Sensors
- Can be turned off by disabling them in the User Configuration File
  - "Sensors": { "Enabled": false, …

important

If the Sensors are disabled, the Pro will not measure Power Consumption and other metrics

Example user.cfg

The factory default configuration from the latest firmware can be downloaded here: user.fac (v0.29)

RockFLEET Assured configurations

RockFLEET Assured is built on the RockBLOCK Pro APNT. The configurations below are the ready-to-deploy settings for the RockFLEET Assured NMEA 2000 and NMEA 0183 versions. What each APNT and Chart setting does is described on the APNT (Iridium STL®) page.

NMEA 2000 version

The following user configuration example shows the required settings for the NMEA 2000 version only.

Download here in ready to deploy state. i.e. without commentary

{
  "Serial":{
    "Enabled":true,
    "mode":"RS4XX_FULL",
    "baud":115200,
    "parity":"NONE",
    "bits":8,
    "stop":1
  },
  "BLE":{
    "Enabled":true,
    "connectionTimeout":300
  },
  "GNSS":{
    "Enabled":true,
    "nmeaForwardEnabled":false,
    "reportInterval":900,             <-----SECONDS BETWEEN EACH POSITION REPORT MADE TO CLOUDLOOP
    "apntMode":"DYNAMIC",             <-----DYNAMIC FOR BETTER TRACKING WHILE MOVING
    "apntKalmanFilter":"MARITIME",
    "apntSensitivity":"HIGH",
    "apntPowerSaving":"FAST",
    "nmeaSentences":{
      "GNGGA":false,
      "GNRMC":false,
      "GPGGA":false,
      "GPRMC":false,
      "GPZDA":false,
      "PJLTPOS":false,
      "PJLTSTAT":false,
      "PJLTSVI":false,
      "PJLTVEL":false,
      "AISVDO":false
    },
    "apntFilterPosition":true,       <-----POSITION REPORT WILL USE THE POSITION WITH THE LOWEST EPE FROM THE LAST 20% OF SET REPORT INTERVAL
    "apntHot":false                  <-----WHEN FALSE THE APNT MODULE WILL ONLY BE POWERED 20 MINUTES BEFORE EACH POSITION REPORT
},
    "Sensors": {
      "Enabled": true
    },
    "IO": {
      "IOtype": "DIGITAL",
      "IOchans": [
        {
          "channelIndex": 1,
          "channelMode": "UNKNOWN",
          "filter": "HIGH",
          "hysteresis": 0.1,
          "threshold": 1.5,
          "reportCoV": 0.0,
          "reportPeriod": 0
        },
        {
          "channelIndex": 2,
          "channelMode": "UNKNOWN",
          "filter": "HIGH",
          "hysteresis": 0.1,
          "threshold": 1.5,
          "reportCoV": 0.0,
          "reportPeriod": 0
        },
        {
          "channelIndex": 3,
          "channelMode": "UNKNOWN",
          "filter": "HIGH",
          "hysteresis": 0.1,
          "threshold": 1.5,
          "reportCoV": 0.0,
          "reportPeriod": 0
        },
        {
          "channelIndex": 4,
          "channelMode": "UNKNOWN",
          "filter": "HIGH",
          "hysteresis": 0.1,
          "threshold": 1.5,
          "reportCoV": 0.0,
          "reportPeriod": 0
        }
      ]
    },
    "SleepMode": "NONE",
    "LEDS": {
      "Enabled": true
    },
    "Imt": {
      "defaultTopic": 244,
      "defaultTTL": 86400,
      "startupEventEnabled":true
    },
    "BUZZER": {
      "Enabled": true
    },
    "SVI": {
      "reportDuration": 0,
      "reportTopic": 313,
      "reportInterval": 0
    },
    "Chart": {
      "epeScale": 1.0,                   <-----EPE SCALE IS SET TO 1.0, THEREFORE ALARM IS TRIGGERED IF GNSS AIS TARGET IS (1.0 x EPE) AWAY FROM APNT POSITION
      "positionCompareTimer": 10,        <-----SET TO 10, MEANS THAT ALARM WILL TRIGGER EVERY 10 SECONDS IF THE GNSS TARGET WAS OUT OF RANGE
      "utcDifferenceLimit": 0,
      "utcDifferenceTimer": 0,
      "positionValidityTimer": 0,
      "errorCircle": true,               <-----ENABLES THE ACTUAL EPE CIRCLE TO APPEAR ON THE CHART PLOTTER
      "errorLimitCircle": false          <-----ENABLES THE SCALED EPE CIRCLE TO APPEAR ON THE CHART PLOTTER
    }
  }

NMEA 0183 version

The following user configuration example shown below indicates the required settings for the NMEA 0183 version only.

Download here in ready to deploy state. i.e. without commentary

  {
    "Serial": {
      "Enabled": true,
      "mode": "RS4XX_FULL",     <-----SERIAL SETTINGS SET TO WORK FOR RS422 AT 38400 BAUD
      "baud": 38400,
      "parity": "NONE",
      "bits": 8,
      "stop": 1
    },
    "BLE": {
      "Enabled": true,          <-----BLE NEEDS TO BE ON FOR APP
      "connectionTimeout": 300
    },
    "GNSS": {
      "Enabled": true,
      "nmeaForwardEnabled": true,       <-----GNSS & NMEA FORWARDING HAS TO BE ENABLED FOR THE CHART PLOTTER TO FUNCTION
      "reportInterval": 900,            <-----SECONDS BETWEEN EACH POSITION REPORT MADE TO CLOUDLOOP
      "apntMode": "DYNAMIC",            <-----DYNAMIC FOR BETTER TRACKING WHILE MOVING
      "apntKalmanFilter": "MARITIME",
      "apntSensitivity": "HIGH",
      "apntPowerSaving": "FAST",
      "nmeaSentences": {
        "GNGGA": false,
        "GNRMC": false,
        "GPGGA": true,                   <-----GPGGA NEEDS TO BE ON
        "GPRMC": true,                   <-----GPRMC NEEDS TO BE ON
        "GPZDA": false,
        "PJLTPOS": false,                   
        "PJLTSTAT": false,
        "PJLTSVI": false,
        "AISVDO": true                   <-----WHEN TRUE THE AIS MESSAGES WILL BE SENT FOR THE EPE SCALE CIRCLE TO BE DISPLAYED ON THE CHART PLOTTER
      },
      "apntFilterPosition": true,        <-----POSITION REPORT WILL USE THE POSITION WITH THE LOWEST EPE FROM THE LAST 20% OF SET REPORT INTERVAL
      "apntHot": true                    <-----WHEN FALSE THE APNT MODULE WILL ONLY BE POWERED 20 MINUTES BEFORE EACH POSITION REPORT
    },
    "Sensors": {
      "Enabled": true
    },
    "IO": {
      "IOtype": "DIGITAL",
      "IOchans": [
        {
          "channelIndex": 1,
          "channelMode": "UNKNOWN",
          "filter": "HIGH",
          "hysteresis": 0.1,
          "threshold": 1.5,
          "reportCoV": 0.0,
          "reportPeriod": 0
        },
        {
          "channelIndex": 2,
          "channelMode": "UNKNOWN",
          "filter": "HIGH",
          "hysteresis": 0.1,
          "threshold": 1.5,
          "reportCoV": 0.0,
          "reportPeriod": 0
        },
        {
          "channelIndex": 3,
          "channelMode": "UNKNOWN",
          "filter": "HIGH",
          "hysteresis": 0.1,
          "threshold": 1.5,
          "reportCoV": 0.0,
          "reportPeriod": 0
        },
        {
          "channelIndex": 4,
          "channelMode": "UNKNOWN",
          "filter": "HIGH",
          "hysteresis": 0.1,
          "threshold": 1.5,
          "reportCoV": 0.0,
          "reportPeriod": 0
        }
      ]
    },
    "SleepMode": "NONE",
    "LEDS": {
      "Enabled": true
    },
    "Imt": {
      "defaultTopic": 244,
      "defaultTTL": 86400,
      "startupEventEnabled":true
    },
    "BUZZER": {
      "Enabled": true
    },
    "SVI": {
      "reportDuration": 0,
      "reportTopic": 313,
      "reportInterval": 0
    },
    "Chart": {
      "epeScale": 1.0,                   <-----EPE SCALE IS SET TO 1.0, THEREFORE ALARM IS TRIGGERED IF GNSS AIS TARGET IS (1.0 x EPE) AWAY FROM APNT POSITION
      "positionCompareTimer": 10,        <-----SET TO 10, MEANS THAT ALARM WILL TRIGGER EVERY 10 SECONDS IF THE GNSS TARGET WAS OUT OF RANGE
      "utcDifferenceLimit": 0,
      "utcDifferenceTimer": 0,
      "positionValidityTimer": 0,
      "errorCircle": true,               <-----ENABLES THE ACTUAL EPE CIRCLE TO APPEAR ON THE CHART PLOTTER
      "errorLimitCircle": false          <-----ENABLES THE SCALED EPE CIRCLE TO APPEAR ON THE CHART PLOTTER
    }
  }

Serial Communication​

BLE Configuration​

GNSS Configuration (Shared with APNT)​

Sensors​

JAMMING and SPOOFING detection and display settings.​

IO Configuration (GPIO)​

Sleep Mode​

IMT Configuration​

Buzzer configuration. NOT CURRENTLY IMPLEMENTED​

SVI Configuration. RESERVED FOR INTERNAL TEST USE​

Reducing power consumption.​

Example user.cfg​

RockFLEET Assured configurations​

NMEA 2000 version​

NMEA 0183 version​

Serial Communication

BLE Configuration

GNSS Configuration (Shared with APNT)

Sensors

JAMMING and SPOOFING detection and display settings.

IO Configuration (GPIO)

Sleep Mode

IMT Configuration

Buzzer configuration. NOT CURRENTLY IMPLEMENTED

SVI Configuration. RESERVED FOR INTERNAL TEST USE

Reducing power consumption.

Example user.cfg

RockFLEET Assured configurations

NMEA 2000 version

NMEA 0183 version