settings.yml

---
- GPRS:
  - block: >
           These settings are related to the modem and GPRS, and include settings
           for the modem to be able to connect via the SIM card operator to the
           Internet.
  - pin:
      values: 4 digits
      validity: reboot
      default: ""
      desc: SIM PIN. If it is not set, no `AT CPIN` command will be issued to the modem.
  - apn:
      values: string
      validity: reboot
      default: internet
      desc: GPRS access point name
  - apnUser:
      values: string
      validity: reboot
      default: ""
      desc: GPRS access point user-id, required by some providers
  - apnPassword:
      values: string
      validity: reboot
      default: ""
      desc: GPRS access point password (for `apnUser`), required by some providers
  - gprsTimeout:
      values: 0...
      validity: next loop
      default: 600
      desc: time in seconds after which the system no longer expects GPRS, 0 means no monitoring
  - cellInfo:
      values: 0/1
      validity: cell change
      default: 0
      desc: Whether or not to publish cellinfo when a new GSM cell is detected
 
- Device:
  - block: >
           The device-related settings lay down how the device operates in general.
           Particular attention should be paid to the _OTAP_ settings if OTAP is
           required.
  - sleep:
      values: 0..
      validity: reboot
      default: 21600
      desc: sleep <sleep> seconds after device off before device is woken up by clock (21600s ~ 6 hours)
  - motion:
      values: 0,1..255
      validity: reboot
      default: 4
      desc: Sensitivity for motion sensor. 0=off, 1=highest sensitivity
  - otapUser:
      values: string
      validity: upgrade
      default: ""
      desc: HTTP basic auth username for OTAP
  - otapPassword:
      values: string
      validity: upgrade
      default: ""
      desc: HTTP basic auth password for OTAP, related to `otapUser`.
  - otapURI:
      values: string
      validity: upgrade
      default: ""
      desc: URL to `OwnTracks.jad` for OTAP.
  - notifyURI:
      values: string
      validity: upgrade
      default: ""
      desc: optional URL to POST result of an OTAP upgrade. If this is not set, no notification will be posted
  - versionURI:
      values: string
      validity: immediate
      default: ""
      desc: optional URL to check for app version updates. If not set, version checking is off
  - versionInterval:
      values: integer
      validity: immediate
      default: 10800
      desc: interval (default 3 hours) in which the app version is checked (see `versionURI`)
  - lowBattery:
      values: integer
      validity: immediate
      default: 3599
      desc: Threshold for low battery in mV (e.g. battery voltage below 3.599V will switch off the device)
  - dExtVoltage:
      values: integer
      validity: immediate
      default: 500
      desc: controls the external voltage monitoring. Reports when voltage varies by more than the value given as mV
  - dBattVoltage:
      values: integer
      validity: immediate
      default: 100
      desc: controls the battery voltage monitoring. Reports when voltage varies by more than the value given as mV
  - battery:
      values: 0/1
      validity: reboot
      default: 0
      desc: if 0, device will shutdown when external power is disconnectd. if 1, device will keep running until lowBattery is detected
  - useGPIO1:
      values: 0/1
      validity: immediate
      default: 0
      desc: if true, device will report initial state and changes to GPIO1
  - useGPIO2:
      values: 0/1
      validity: immediate
      default: 0
      desc: if true, device will report initial state and changes to GPIO2 (advanced Greenwich only)
  - useGPIO3:
      values: 0/1
      validity: immediate
      default: 0
      desc: if true, device will report initial state and changes to GPIO3
  - useGPIO5:
      values: 0/1
      validity: immediate
      default: 0
      desc: if true, device will report initial state and changes to GPIO5 (advanced Greenwich only)
  - fmsInterval:
      values: 0,1...
      validity: immediate
      default: 0
      desc: if > 0, device will try to connect every fmsInterval seconds via Can Bus to get fms data and publish to mqtt
  - fmsLoops:
      values: 1... 
      validity: immediate
      default: 30
      desc: sets the number of consecutive FMS data reads before closing the interface
  - fmsIdle:
      values: 1... 
      validity: immediate
      default: 60
      desc: the idle interval between data reads in s 
  - fmsSpeed:
      values: "25|125|250|500|1000"
      validity: immediate
      default: "250"
      desc: Can Bus baud rates in kbps
  - fmsMode:
      values: "STD|EXT"
      validity: immediate
      default: "EXT"
      desc: Can bus modes STD=11 bit, EXT= 29 bit (restricting the number of modes up the data collection cycle)
  - fmsState:
      values: "ACTIVE|SILENT"
      validity: immediate
      default: "SILENT"
      desc: Can bus handling

  - obd2Interval:
      values: 0,1...
      validity: immediate
      default: 0
      desc: "if > 0, device will try to connect every obd2Interval seconds via Can Bus to get ODB2 data including vehicle information, trouble codes, etc. and publish to mqtt"
  - obd2Sensors:
      values: 0,1...
      validity: immediate
      default: 0
      desc: if > 0, device will try to connect every obd2Interval seconds via Can Bus to get ODB2 sensor data and publish to mqtt
  - obd2Addresses:
      values: comma separated list of obd2 controller addresses to scan (use lower case, 8 character hex values)
      validity: immediate
      default: "`000007e8` for STD (11 bit) addressing, `18daf110` for EXT (29 bit) addressing"
      desc: device addresses to listen to (restricting the number of addresses speeds up the data collection cycle)
  - obd2Speeds:
      values: comma separated list of obd2 speeds to try scanning
      validity: immediate
      default: "25,125,250,500,1000"
      desc: Can Bus baud rates in kbps (restricting the number of speeds up the data collection cycle)
  - obd2Modes:
      values: comma separated list of obd2 modes to try scanning
      validity: immediate
      default: "STD,EXT"
      desc: Can bus modes STD=11 bit, EXT= 29 bit (restricting the number of modes up the data collection cycle)

- MQTT:
  - block: >
           This section documents the MQTT-related parameters. Of particular importance
           are `host` and `port`, where the former also contains a _scheme_. For securely
           connecting to a TLSv1 broker, make sure to specify the `ssl://` scheme in the
           `host` setting.


           MQTT topics are used as follows: `publish` specifies a top-level topic branch
           to which the device publishes. The configured `clientID` (which defaults to
           the device's IMEI) is appended to that. The device subscribes to the `subscription`
           topic (default's to `publish/clientID/cmd`) for commands.

  - cleanSession:
      values: 0/1
      validity: reboot
      default: "0"
      desc: Whether or not to set the MQTT _cleanSession_ flag.
  - clientID:
      values: string
      validity: reboot
      default: "IMEI"
      desc: Used in MQTT connect and appended to `publish` topic.
  - fields:
      values: ""
      validity: immediate
      default: _see text_
      desc: Comma separated list of optional fields in published message. May include any of `course`, `speed`, `altitude`, `distance`, `battery`, `trip`. Defaults to `course,speed,altitude,distance,trip`
  - host:
      values: string
      validity: reboot
      default: ""
      desc: Scheme and hostname or IP address to connect to. Valid schemes are `tcp:` and `ssl:`
  - keepAlive:
      values: "1.."
      validity: reboot
      default: 60
      desc: MQTT keepalive in seconds
  - mqttTimeout:
      values: 0-..
      validity: next loop
      default: 600
      desc: time in seconds after which device no longer expects establishing an MQTT connection, 0 means no monitoring.
  - port:
      values: 1-..
      validity: reboot
      default: 1883
      desc: TCP/UDP port to connect to. When using `ssl://` in `host`, this should probably be changed to, say, 8883.
  - qos:
      values: 0-2
      validity: reboot
      default: 1
      desc: Quality of Service (QoS) for MQTT publishes
  - retained:
      values: 0/1
      validity: reboot
      default: 1
      desc: Publish locations with a retained flag
  - user:
      values: ""
      validity: reboot
      default: ""
      desc: Username for MQTT connect. Default means no authentication
  - password:
      values: ""
      validity: reboot
      default: ""
      desc: Password for MQTT connect.
  - publish:
      values: ""
      validity: reboot
      default: owntracks/gw/
      desc: Base topic for MQTT publishes. Note, you'll want a trailing slash on this.
  - subscription:
      values: ""
      validity: reboot
      default: "../cmd"
      desc: Device listens for commands at this topic
  - subscriptionQos:
      values: "0..2"
      validity: reboot
      default: "2"
      desc: QoS for `subscription`
  - tid:
      values: "alnum"
      validity: next pub
      default: "<xx>"
      desc: Short tracker-ID, typically two letters, which defaults to last two characters of `clientID`
  - will:
      values: ""
      validity: reboot
      default: "0"
      desc: The message published as LwT
  - willQos:
      values: "0..2"
      validity: reboot
      default: "1"
      desc: QoS for `willTopic` publish
  - willRetain:
      values: "0/1"
      validity: reboot
      default: "1"
      desc: Wether or not to retain the message published to `willTopic`
  - willTopic:
      values: ""
      validity: reboot
      default: see above
      desc: Topic for MQTT Last Will and Testament

- Sensors:
  - block: |
           The SensorManager is responsible for monitoring and publishing sensor values.
           Currently 2 temperature sensors are supported. 

  - temperatureInterval:
      values: "0-..., typical value 60 (seconds)"
      validity: reboot
      default: "0"
      desc: Interval for requesting new sensor values in seconds. 0 means, no monitoring
  - dTemperature:
      values: "0-..."
      validity: immediate
      default: "1"
      desc: threshold for temperature updates in 0.01 degrees Celsius. E.g. if set to 10, changes in temperature will only be published if the difference to the last published value is > 0.1 degrees Celsius.

- LocationManager:
  - block: |
           The LocationManager is responsible for determining when to publish
           a location. These settings can be used to alter its behaviour and
           they influence _how often_ data is published.

           `minSpeed` should probably be set to about 5 km/h when in a vehicle; it
           means whenever the vehicle slows down to below this value it transmits
           a `k` message (park) and transmits and enters _drive mode_ when it
           accelerates over 5 km/h.

           The two parameters influencing the precision/data volume from a user point of view are
           `minInterval` and `maxInterval`. The following scenarios show examples:
           
           * For low data volume (few publishes): `maxInterval=300` (5min),
             `minInterval=18000` (5h).  While driving, report every 5 minutes
             when actually moving and everytime the car stops.  Autobahn 5min at
             6-20 km, small roads 6 km, towns probably only when stopped. While
             parked, typically overnight, will give 2 positions before started
             again next morning.  Useful when general information is necessary.
           
           * medium publishes: `maxInterval=60`, `minInterval=9000` (2,5h)
             Reports on Autobahn (at 80-240kmh) every 1.3-4km, on small roads
             (at 75kmh) every 1,2 km, in town (30 kmh) every 500 m. This
             setting would allow to actually follow a vehicle whithout missing
             significant crossroads or landmarks.
           
           * frequent publishes (high precision): `maxInterval=5`, `minInterval=3600` (1h)
             While driving, report every 5 seconds when actually moving and everytime the car stops.
             Autobahn every 100 m - 300 m, small roads every 80m, towns every
             40m. This would allow to follow the vehicle as it moves on screen.
             It would allow for speed monitoring.
           
           Settings for pedestrians, runners, bicycle riders, race cars would be different.

           Controlled by the setting `offUntil`, given as a Unix epoch timestamp in seconds,
           the GW will suspend publishing GPS positions until after the given timestamp.
           None of _first_, _move_, _park_, _transition_, _lost_ or any other
           triggers will be active. Trip calculation is suspended too. The
           setting is persistent: Even after reboot or restart by alarm clock,
           the suspension remains active.  The only exceptions are the wakeup by
           accerelometer (alarm), which will publish a location, and the `gps` command
           which will report the last-known (and thus non-secret) location. Starting with
           v0.11.42, the `offUntil` setting, when active, will cause the device to *not*
           transmit any location messages, alarms, any voltage messages, cellInfo, operators,
           FMS or OBD2 messages. The `state` command's response will neither contain cellinfo
           nor operators in it. In addition, `lastFix` is neither stored nor updated, nor
           is the trip counter updated. What *is* transmitted, is the `start` message. The
           response to the `gps` command will contain `"no location available"`.
                 
  - sensitivity:
      values: "0-..."
      validity: immediate
      default: "1"
      desc: Threshold in meters to exclude movement artifacts from trip calculation
  - minSpeed:
      values: "0-..."
      validity: immediate
      default: "5"
      desc: Mininum speed in Km/h to switch to _move_ mode
  - minDistance:
      values: "0-..."
      validity: immediate
      default: "100"
      desc: Distance since last publish in meters to switch to _move_ mode
  - maxInterval:
      values: "0-..."
      validity: immediate
      default: "60"
      desc: Maximum time in seconds before next publish in _move_ mode
  - minInterval:
      values: "0-..."
      validity: immediate
      default: "3600"
      desc: Mininum time in seconds before publish in _stationary_ (park) mode
  - fixTimeout:
      values: "0-..."
      validity: immediate
      default: "600"
      desc: Time in seconds after which the device no longer expects a GPS fix, 0 means no monitoring
  - offUntil:
      values: "0,1-..."
      validity: immediate
      default: "0"
      desc: timestamp in UNIX epoch (seconds since 1970-01-01 00:00) until location publishes are suspended
  - maxSize:
      values: "numeric"
      validity: reboot
      default: "1048576"
      desc: maximum size of persistent message store in bytes (default = 1 MB). When app starts and no unsent records are in storage, storage is reset.  When storage reaches maxSize and all records are sent, storage is reset while running.  When storage reaches maxSize, new records are not stored anymore. Do not set to < 1024
  - raw:
      values: 0/1
      validity: immediate
      default: 1
      desc: Publish raw GPS string to the `../raw` topic
  - payload:
      values: "csv/json"
      validity: "immediate"
      default: "json"
      desc: Publish payload in JSON or CSV format
  - killQueue:
      values: "0/1"
      validity: "reboot"
      default: "0"
      desc: emergency functionality removes queue file when set to "1". The parameter is set to "0" afterwards.
  - killTrip:
      values: "0/1"
      validity: "reboot"
      default: "0"
      desc:  emergency functionality removes the persistent trip counter file when set to "1". The parameter is set to "0" afterwards.
      

- Debugging and Logging:
  - block: |
       The app provides debug and logging information prioritised and categorised by component.

       The used priorities are specified by a character (similar to syslog) with "P" for emergency beeing the highest priority:

       * `P` Emergency (Panic)
       * `A` Alert
       * `C` Critical
       * `E` Error
       * `W` Warning
       * `N` Notice
       * `I` Informational
       * `D` Debug

       Debug and logging output can be written to the standard error stream
       (typically a connected terminal), a file on the device (`log.txt`), and it can be
       published via MQTT to the `../log` topic.

       The level of output is specified by the settings

       * `stderrLogLevel`
       * `fileLogLevel`
       * `topicLogLevel`

       The specified character assigned to each of the output media limits the
       output to priorities higher or equal to the priority given. Examples:

       `stderrLogLevel=D`, all logging levels and debug is written to standard error.
       `topicLogLevel=C`, only critical, alert and emergency log messages are sent via MQTT.
       `fileLogLevel=E`, error, critical, alert, and emergency log messages are written to the local file. Warning, notice, informational anddebug messages are ignored

       To limit the amount of debug messages, the set of components for which the messages are written can be controlled by the `dbgComp` parameter. If set to `"all"`, all debug messages are shown. When `"none"` is specified, no debug messages will be shown. `"none" is the default value.

       Otherwise a comma separated list of components allows granular control of the output (e.g. `"AppMain,LocationManager"`). Currently the following components exist:

       * AppMain
       * ATManager
       * BatteryManager
       * CommASC0Thread
       * CommGPSThread
       * CommandProcessor
       * DateFormatter
       * GPIO6WatchDogTask
       * GPIOManager
       * LocationManager
       * MQTTHandler
       * MicroManager
       * ProcessSMSThread
       * Settings
       * SocketGPRSThread
       * SSLSocketFactory
       * UserwareWatchDogTask
       * Can
       * CanRaw
       * VersionChecker

  - dbgComp:
      values: list
      validity: immediate
      default: "none"
      desc: comma-separated list of components to debug; controls the debug output e.g. `"AppMain,LocationManager"`
  - stderrLogLevel:
      values: string
      validity: immediate
      default: "D"
      desc: controls the logging to the device's standard error device (terminal)
  - fileLogLevel:
      values: string
      validity: immediate
      default: "E"
      desc: controls the logging into the device's log file
  - topicLogLevel:
      values: string
      validity: immediate
      default: "E"
      desc: controls the logging to the MQTT broker on `../log/<priority>/<log-message>`
  - usbDebug:
      values: "0/1"
      validity: immediate
      default: "0"
      desc: if set to 1, debug output flows to USB instead of ASC0 via standard error

- Miscellaneous:
  - block: >
           
  - secret:
      values: digits
      validity: immediate
      default: "1234567890"
      desc: The secret required to issue a `login` command to the device
  - loginTimeout:
      values: 0-...
      validity: immediate
      default: "600"
      desc: Successful logins expire after this number of seconds