System IDs
==========

Every value a device stores or exchanges with the server is addressed
by a numeric **system ID** (a HiGPS parameter ID). The registry lives
in ``databaseParams`` in the user-editable ``last.py`` and is passed
into the database constructor: ``db = database(databaseParams)``.

Which IDs a device actually registers is up to its ``last.py``: the
findyIoT module uses the *Identity & system*, *Network status*, *OTA
update* and *Commands* groups; the measurement, calibration and channel
groups belong to Logger Pro's sensor front-end.

Entry format
------------

Each registry entry is a list::

    "421": ["W", 0, 0, 0, "900", "R"]

.. list-table::
   :header-rows: 1
   :widths: 12 88

   * - Index
     - Meaning
   * - 0
     - Allowed operations: ``"R"`` read-only, ``"W"`` read-write,
       ``"E"`` execute (the server can trigger it as a command)
   * - 1
     - Type: ``0`` string, ``1`` number, ``2`` boolean, ``3`` buffer,
       ``9`` function
   * - 2
     - Storage: ``0`` file system (btree), ``1`` RAM, ``2`` function
   * - 3
     - Path: ``0`` default, or the function name for ``"E"`` entries
   * - 4
     - Default value (written on factory reset / first boot)
   * - 5
     - Legacy field, kept for wire compatibility

Identity & system
-----------------

.. list-table::
   :header-rows: 1
   :widths: 10 12 78

   * - ID
     - Ops
     - Meaning
   * - 200
     - R
     - Device IMEI
   * - 421
     - W
     - Measurement/wakeup period in seconds (main cycle)
   * - 422
     - W
     - Report period in seconds; must be >= 421 (a report is sent every
       422/421 wakeups)
   * - 440
     - R
     - Current alarm code (0 = no alarm; otherwise the ID of the
       parameter that triggered it)
   * - 443
     - R
     - Timestamp of the last successful report
   * - 522
     - R
     - Wakeups since the last sent report
   * - 587
     - W
     - Sensor warm-up time in seconds before measuring (Logger Pro)

Measurements
------------

.. list-table::
   :header-rows: 1
   :widths: 10 12 78

   * - ID
     - Ops
     - Meaning
   * - 290
     - R
     - External power (mV)
   * - 437 / 439
     - R
     - Cumulative pulse count, digital input 1 / 2
   * - 520 / 570
     - R
     - Last raw reading, analog input 1 / 2 (4-20 mA)
   * - 582
     - R
     - 0-5 V analog input, last value
   * - 594 / 595
     - R
     - Packed float history buffers, analog input 1 / 2
   * - 540 / 541
     - W (buffer)
     - Pulse ring-buffers for input 1 / 2
   * - 538 / 539
     - W
     - Current slot index of ring-buffer 540 / 541
   * - 532 / 533
     - R
     - Previous ULP edge-counter value (overflow tracking)

Calibration & alarms
--------------------

.. list-table::
   :header-rows: 1
   :widths: 14 12 74

   * - ID
     - Ops
     - Meaning
   * - 523 / 524 / 525
     - W
     - AIN1 alarm: minimum (mA) / maximum (mA) / enable
   * - 553 / 554
     - W
     - AIN1 scaling: sensor current at range low / high (mA)
   * - 555 / 556
     - W
     - AIN1 scaling: engineering value at range low / high
   * - 575 / 576 / 577
     - W
     - AIN2 alarm: minimum (mA) / maximum (mA) / enable
   * - 578 / 579
     - W
     - AIN2 scaling: sensor current at range low / high (mA)
   * - 580 / 581
     - W
     - AIN2 scaling: engineering value at range low / high

Channel enables & outputs
-------------------------

.. list-table::
   :header-rows: 1
   :widths: 10 12 78

   * - ID
     - Ops
     - Meaning
   * - 636
     - W
     - Enable digital input 1 sampling (report adds 437/540)
   * - 637
     - W
     - Enable digital input 2 sampling (report adds 439/541)
   * - 638
     - W
     - Enable analog input 1 sampling (report adds 594/520)
   * - 639
     - W
     - Enable analog input 2 sampling (report adds 570/595)
   * - 640
     - W
     - Relay On - energize the 5 V / 12 V rails during ``measure()``

Network status
--------------

.. list-table::
   :header-rows: 1
   :widths: 10 12 78

   * - ID
     - Ops
     - Meaning
   * - 230
     - R
     - Network bearer (GSM / NB-IoT / Cat-M / LTE)
   * - 231
     - R
     - RSSI
   * - 232
     - R
     - Link quality / RSRQ
   * - 234
     - R
     - Cell ID
   * - 235 / 236
     - R
     - MNC / MCC
   * - 237
     - R
     - SINR
   * - 238
     - R
     - LAC

OTA update
----------

.. list-table::
   :header-rows: 1
   :widths: 10 12 78

   * - ID
     - Ops
     - Meaning
   * - 51
     - W
     - OTA package name on the server - a stored (uncompressed) ZIP
       archive (set by the server)
   * - 52
     - E
     - Apply the downloaded update (``update()``)
   * - 53
     - R
     - Update state: 0 idle, 1 downloading, 2 downloaded / ready,
       3 updating
   * - 54
     - R
     - Update result: 0 none, 1 ok, 4 connection lost (resumable),
       5 integrity check failed, 6 unsupported package, 7 invalid
       size / URI, 8 apply failed / new firmware does not boot
   * - 55
     - E
     - Download the package (``downloadUpdate()``) - see
       :doc:`/guides/ota-update`

Commands
--------

.. list-table::
   :header-rows: 1
   :widths: 10 12 78

   * - ID
     - Ops
     - Meaning
   * - 221
     - E
     - Restart the device (``restart()``)
   * - 222
     - E
     - Factory reset - wipe the database, rewrite defaults
       (``factoryReset()``)
   * - 312
     - E
     - Upload the current settings (``get_settings()``)
   * - 429
     - E
     - ``resetCount1()`` - Logger Pro: reset the pulse counters;
       findyIoT module: reset and re-register the modem

Adding your own IDs
-------------------

Pick a free numeric ID, add the row to ``databaseParams`` in
``last.py`` and it becomes readable/writable over the protocol
immediately - no framework change needed. See
:doc:`/guides/getting-started`.