MQTTPublishMeta()
=================

Publish custom metadata called by the CRBasic program.


.. admonition:: Syntax

   **MQTTPublishMeta** (Result, "TableName", "FieldName", "Key", "Value", "OptionalTopicSegment")

   - ``Result`` {*float* | *long*} :
     Response code

     - ``0`` = Success
     - ``-1`` = No MQTT connection
     - ``-2`` = TableName or FieldName not found
     - ``-5`` = System error
     - ``-6`` = Did not run

   - ``"TableName"`` {*string*} or {NULL string ""} :
     Specifies what data table to target. The ``TableName`` will be
     included in the topic structure. If a null string is supplied, the
     segment is omitted from the topic structure.

   - ``"FieldName"`` {*string*} or {NULL string ""} :
     Specifies what field name in a data table to target. The
     ``FieldName`` will be included in the topic structure. If a null
     string is supplied, the segment is omitted from the topic structure.

   - ``"Key"`` {*string*} :
     Specifies the JSON key to publish. The provided ``Key`` is used
     directly as the JSON key and is paired with the value supplied in
     ``Value``.

   - ``"Value"`` {*float* | *long* | *string* | *boolean* | *double*} :
     The provided ``Value`` is encoded into JSON and published as the
     JSON value for the given ``Key``.

   - ``"OptionalTopicSegment"`` {*string*} *(Optional)* :
     Adds an extra topic level. When provided, this segment is appended
     to the topic structure where the ``Key`` and ``Value`` are
     published.


:guilabel:`Topic Structure` ``<base topic>/pr/<UID>/metadata/#``

.. admonition:: Example Topic Structures Based on Parameters

    - MQTTPublishMeta(meta_data_result, "", "", "<Key>", "<Value>")
      
      - :guilabel:`Topic` <base topic>/pr/<UID> **/metadata**   

    - MQTTPublishMeta(meta_data_result, "", "", "<Key>", "<Value>", "<OptionalTopicSegment>")

      - :guilabel:`Topic` <base topic>/pr/<UID> **/metadata/<OptionalTopicSegment>**    

    - MQTTPublishMeta(meta_data_result, "<TableName>", "", "<Key>", "<Value>")

      - :guilabel:`Topic` <base topic>/pr/<UID> **/metadata/<TableName>**    

    - MQTTPublishMeta(meta_data_result, "<TableName>", "<FieldName>", "<Key>", "<Value>")

      - :guilabel:`Topic` <base topic>/pr/<UID> **/metadata/<TableName>/<FieldName>**    

    - MQTTPublishMeta(meta_data_result, "<TableName>", "<FieldName>", "Key", "Value", "<OptionalTopicSegment>")

      - :guilabel:`Topic` <base topic>/pr/<UID> **/metadata/<TableName>/<FieldName>/<OptionalTopicSegment>**    
    
    - MQTTPublishMeta(meta_data_result, "<TableName>", "", "Key", "Value", "<OptionalTopicSegment>")

      - :guilabel:`Topic` <base topic>/pr/<UID> **/metadata/<TableName>/<OptionalTopicSegment>**   


Data Format Structure
---------------------

:guilabel:`Payload` JSON

.. code-block:: json

    {
      "notice": {
        "UID": "<UID>",
        "timestamp": "yyyy-mm-ddThh:mm:ss",
        "<Key>": "<Value>"
      }
    }


CRBasic Example
---------------

.. code-block:: basic

    Const LONGITUDE = -111.8549
    Const LATITUDE  = 41.7666
    Const ALTITUDE  = 4498

    Public engine_rpm As Long
    Public fuel_level As Float
    Public pto_engaged As Boolean
    Public tire_pressure(4) As Float
    Public meta_data_result
    Public trigger as Boolean

    DataTable (Deere_4020_Chart, 1, -1)
      DataInterval (0, 10, Sec, 10)
      Sample (1, engine_rpm, Long)
      Sample (1, fuel_level, IEEE4)
      Sample (1, pto_engaged, Boolean)
      Sample (4, tire_pressure(), IEEE4)
      MQTTPublishTable (1, 0, 10, Sec, 2, LONGITUDE, LATITUDE, ALTITUDE)
    EndTable

    'Main Program
    BeginProg

      'Test Values
      engine_rpm        = 1800
      fuel_level        = 100
      pto_engaged       = True
      tire_pressure(1)  = 32.1
      tire_pressure(2)  = 32.2
      tire_pressure(3)  = 35.1
      tire_pressure(4)  = 35.2

      Scan (10, Sec, 0, 0)

        'Trigger MQTTPublishMeta() Examples:
        If trigger = True Then
          trigger = False   ' reset trigger

          '1 - Topic: <base topic>/pr/<UID>/metadata
          ' - Only the key:value are used
          MQTTPublishMeta (meta_data_result, "", "", "farm_name", "Twin Pines")

          '2 - Topic: <base topic>/pr/<UID>/metadata/established
          ' - OptionalTopicSegment = established
          MQTTPublishMeta (meta_data_result, "", "", "date", "11/05/1955", "established")

          '3 - Topic: <base topic>/pr/<UID>/metadata/Deere_4020_Chart
          ' - TableName = Deere_4020_Chart
          MQTTPublishMeta (meta_data_result, "Deere_4020_Chart", "", "VIN", "JD4020-000001")

          '4 - Topic: <base topic>/pr/<UID>/metadata/Deere_4020_Chart/engine_rpm
          ' - TableName = Deere_4020_Chart
          ' - FieldName = engine_rpm
          MQTTPublishMeta (meta_data_result, "Deere_4020_Chart", "engine_rpm", "rpm_range", "1500-2202")

          '5 - Topic: <base topic>/pr/<UID>/metadata/Deere_4020_Chart/engine_rpm/pto_rpm
          ' - TableName = Deere_4020_Chart
          ' - FieldName = engine_rpm
          ' - OptionalTopicSegment = pto_rpm
          MQTTPublishMeta (meta_data_result, "Deere_4020_Chart", "engine_rpm", "pto_rpm", "540", "pto_rpm")

          '6 - Topic: <base topic>/pr/<UID>/metadata/Deere_4020_Chart/engine_type
          ' - TableName = Deere_4020_Chart
          ' - OptionalTopicSegment = engine_type
          MQTTPublishMeta (meta_data_result, "Deere_4020_Chart", "", "type", "6.6L Diesel", "engine_type")
        EndIf

        CallTable Deere_4020_Chart

      NextScan
    EndProg


**Example Data** 

The following example data corresponds to the 4th example in the CRBasic example.

:guilabel:`Subscribe` ``cs/v2/pr/ABCD-EFGH-1234/metadata/Deere_4020_Chart/engine_rpm``

.. code-block:: json

    {
      "notice": {
        "UID": "ABCD-EFGH-1234",
        "timestamp": "2026-01-31T12:14:00",
        "rpm_range": "1500-2202"
      }
    }