Signals layer

A signals layer is where words (8-, 16- and 32-bit) that represent application values for sensors (e.g. temperature, humidity, motor speed) and commands (e.g. "set motor position to this"). A MIN-based system will publish (i.e. generate) signals through an API and consume (i.e. subscribe) to signals. Signals are then mapped into MIN frames that carry them.

The signals are defined in a JSON file in a format like this:

  "signals": [
    {
      "handle": "s1",
      "c_type": "uint8_t",
      "update_bit": true,
      "display_name": "Temperature C",
      "definition": "Temp = val * 0.0625"
    },
    {
      "handle": "s2",
      "c_type": "uint16_t",
      "display_name": "Pressure"
    }
  ]

A building tool parses this and generates a C header file for the application to include that allows these signals to be read and written. The signal definition includes not only the C type but also how to display the signal in a human-readable format (this is intended for the building tool to generate a Wireshark dissector in LUA that will translate MIN frames directly into signals).

An update bit can be tagged to a signal. This is a flag that indicates whether the signal has been written since the last time the frame containing is has been sent. This allows event-based consumption of signals, which is particularly useful for commands like "move the motor to this position".

The specific mapping of these signals is also defined in the JSON file:

  "frames": [
    {
      "min_id": "auto",
      "handle": "f1",
      "display_name": "Sensor data",
      "period_ms": 120.0,
      "signals": [
        "s1",
        "s2",
        "s3"
      ]
    },
    {
      "handle": "f3",
      "min_id": 56,
      "display_name": "Button press",
      "period_ms": 250.0,
      "offset_ms": 100.0,
      "force_transmit": "i1",
      "signals": [
        "i1"
      ]
    }
  ]

The code to map signals into frames is automatically generated by the building tool. A frame can be transmitted periodically (driven by a simple periodic call from the application to the MIN signals layer) or 'force transmit' (i.e. queued immediately after a specific signal is written). Force transmit frames are useful for carry event-based data (particularly if a set of parameters are needed: all the signals in a group are written and the last triggering signal is then sent to force the whole group to be sent).

If a period is given for a force transmit frame then the signals layer will hold over the transmission of the frame (to save overloading the serial link or the receiving node). If all the frames have period values given to them then the building tool can calculate the peak load on the serial link and verify it can handle the traffic. It can also use calculate the buffering requirements for MIN and generate the setup for the serial drivers.

The frames section also allows 'raw' frames to be defined: in effect, the raw MIN protocol is exposed to the application, in case such frames are needed (e.g. for implementing block message transfers).

A future goal for the signals layer is for it to use the reserved MIN identifier of 0xff to publish a URL and a hash so that a receiving PC can download the JSON configuration file used. This will allow a test tool to be able to connect to any MIN signals system and be able to display human-readable data from the application.