Skip to content
A ClearBlade Platform adapter that allows the ClearBlade to interact with the MTAC-GPIO accessory card inserted into a Multitech Conduit gateway.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
edge_scripts
.gitignore
main.go
readme.md

readme.md

mtacGpioAdapter Adapter

The mtacGpioAdapter adapter provides the ability for the ClearBlade platform to interface with the MultiTech MTAC-GPIO accessory card. (https://www.multitech.com/models/94557076LF). Internally, the mtacGpioAdapter adapter utilizes the mts-io package provided by Multitech. The mts_io package provides a sysfs interface to the Multitech Conduit’s various I/O abilities and for the ID info stored in the on-board EEPROM. Sysfs attributes are exported at /sys/devices/platform/mts-io on the device. A shell script mts-io-sysfs is provided as a simple wrapper to the sysfs attributes.

The adapter subscribes to MQTT topics which are used to interact with the mts-io-sysfs utility. The adapter publishes any data retrieved from the mts-io-sysfs utility to MQTT topics so that the ClearBlade Platform is able to retrieve and process mts-io-sysfs utility related data..

mts-io-sysfs Command Documentation

Usage: mts-io-sysfs [ OPTIONS ] OBJECT [--] [ ARGUMENTS ]
where  OBJECT := {
         show SHOW-NAME |
         store STORE-NAME |
       }

       SHOW-NAME := {
         ap1/product-id
         ap1/device-id
         ap1/rts-override
         ap1/vendor-id
         ap1/reset
         ap1/rs4xx-term-res
         ap1/hw-version
         ap1/serial-mode
         ap2/product-id
         ap2/adc0
         ap2/adc1
         ap2/adc2
         ap2/din0
         ap2/din1
         ap2/din2
         ap2/din3
         ap2/led1
         ap2/led2
         ap2/device-id
         ap2/vendor-id
         ap2/dout0
         ap2/dout1
         ap2/dout2
         ap2/dout3
         ap2/reset
         ap2/dout-enable
         ap2/hw-version
         capability/adc
         capability/din
         capability/gps
         capability/dout
         capability/lora
         capability/wifi
         capability/bluetooth
         device-id
         eth-reset
         gnss-int
         gnss-reset
         gpiob/product-id
         gpiob/adc0
         gpiob/adc1
         gpiob/adc2
         gpiob/din0
         gpiob/din1
         gpiob/din2
         gpiob/din3
         gpiob/led1
         gpiob/led2
         gpiob/device-id
         gpiob/vendor-id
         gpiob/dout0
         gpiob/dout1
         gpiob/dout2
         gpiob/dout3
         gpiob/reset
         gpiob/dout-enable
         gpiob/hw-version
         has-radio
         hw-version
         imei
         led-a
         led-b
         led-c
         led-cd
         led-d
         led-sig1
         led-sig2
         led-sig3
         led-status
         mac-eth
         mfser/product-id
         mfser/device-id
         mfser/rts-override
         mfser/vendor-id
         mfser/reset
         mfser/rs4xx-term-res
         mfser/hw-version
         mfser/serial-mode
         product-id
         radio-power
         radio-reset
         radio-reset-backoff-index
         radio-reset-backoff-seconds
         radio-reset-backoffs
         reset
         reset-monitor
         reset-monitor-intervals
         usbhub-reset
         uuid
         vendor-id
         wifi-bt-int
         wifi-bt-lpmode
         wifi-bt-lpwkup
         wifi-bt-reset
         wifi-bt-ulpwkup
       }

       STORE-NAME := {
         ap1/rts-override BOOLEAN
         ap1/reset BOOLEAN
         ap1/rs4xx-term-res BOOLEAN
         ap1/serial-mode { loopback | rs232 | rs485-half | rs422-485-full }
         ap2/led1 BOOLEAN
         ap2/led2 BOOLEAN
         ap2/dout0 BOOLEAN
         ap2/dout1 BOOLEAN
         ap2/dout2 BOOLEAN
         ap2/dout3 BOOLEAN
         ap2/reset BOOLEAN
         ap2/dout-enable BOOLEAN
         eth-reset BOOLEAN
         gnss-int BOOLEAN
         gnss-reset BOOLEAN
         gpiob/led1 BOOLEAN
         gpiob/led2 BOOLEAN
         gpiob/dout0 BOOLEAN
         gpiob/dout1 BOOLEAN
         gpiob/dout2 BOOLEAN
         gpiob/dout3 BOOLEAN
         gpiob/reset BOOLEAN
         gpiob/dout-enable BOOLEAN
         has-radio BOOLEAN
         led-a BOOLEAN
         led-b BOOLEAN
         led-c BOOLEAN
         led-cd BOOLEAN
         led-d BOOLEAN
         led-sig1 BOOLEAN
         led-sig2 BOOLEAN
         led-sig3 BOOLEAN
         led-status BOOLEAN
         mfser/rts-override BOOLEAN
         mfser/reset BOOLEAN
         mfser/rs4xx-term-res BOOLEAN
         mfser/serial-mode { loopback | rs232 | rs485-half | rs422-485-full }
         radio-power BOOLEAN
         radio-reset { 0 }
         radio-reset-backoff-index BOOLEAN
         radio-reset-backoffs BOOLEAN
         reset-monitor { pid short-signal long-signal [extra-long-signal] }
         reset-monitor-intervals { short-interval long-interval }
         usbhub-reset BOOLEAN
         wifi-bt-int BOOLEAN
         wifi-bt-lpmode BOOLEAN
         wifi-bt-lpwkup BOOLEAN
         wifi-bt-reset BOOLEAN
         wifi-bt-ulpwkup BOOLEAN
       }

       OPTIONS := {
         --verbose
       }

       BOOLEAN := { OFF | ON }
       OFF := 0
       ON := 1

MQTT Topic Structure

The mts-io adapter utilizes MQTT messaging to communicate with the ClearBlade Platform. The mts-io adapter will subscribe to a specific topic in order to handle mts-io-sysfs utility requests. Additionally, the mts-io adapter will publish messages to MQTT topics in order to communicate the results of requests to client applications. The topic structures utilized by the mts-io adapter are as follows:

  • Read mts-io data request: {TOPIC ROOT}/read/request
  • Read mts-io data response: {TOPIC ROOT}/read/response
  • Write mts-io data request: {TOPIC ROOT}/write/request
  • Write mts-io data response: {TOPIC ROOT}/write/response

MQTT Payloads

The JSON payloads expected by and returned from the mtacGpioAdapter adapter should have the following formats:

Read MTAC-GPIO data request

The json request should be structured as follows:

{
  “action”: “read”,
  "gpio": {
    "digital": {
      "input": {
        “StartAddress”: 0,
        “AddressCount”: 4
      },
      "output": {
        “StartAddress”: 0,
        “AddressCount”: 4
      },
    },
    "analog": {
      "input": {
        “StartAddress”: 0,
        “AddressCount”: 4
      }
    },
  }
}

Write mts-io data request

The json request should resemble the following:

{
  “action”: “write”,
  "gpio": {
    "digital": {
      “StartAddress”: 0,
      “AddressCount”: 4,
      “Data”: [true, false, false, true]
    }
  }
}

Read mts-io data response

The json response will resemble the following:
{
  “success”: true|false,
  “error”: “the error message”,
  “timestamp”: the_timestamp,
  “action”: “read”,
  "gpio": {
    "digital": {
      "input": {
        “StartAddress”: 0,
        “AddressCount”: 4,
        “Data”: [true, false, false, true]
      },
      "output": {
        “StartAddress”: 0,
        “AddressCount”: 4,
        “Data”: [true, false, false, true]
      },
    },
    "analog": {
      "input": {
        “StartAddress”: 0,
        “AddressCount”: 3,
        “Data”: [1, 2, 3]
      }
    },
  }
}

Write mts-io data response

The json response will resemble the following:
{
  “success”: true|false,
  “error”: “the error message”,
  “timestamp”: the_timestamp,
  “action”: “write”,
  "gpio": {
    "digital": {
      “StartAddress”: 0,
      “AddressCount”: 4,
      “Data”: [true, false, false, true]
    },
    "analog": {
      “StartAddress”: 0,
      “AddressCount”: 4,
      “Data”: [1, 2, 3, 4]
    },
  }
}

ClearBlade Platform Dependencies

The mtacGpioAdapter adapter was constructed to provide the ability to communicate with a System defined in a ClearBlade Platform instance. Therefore, the adapter requires a System to have been created within a ClearBlade Platform instance.

Once a System has been created, artifacts must be defined within the ClearBlade Platform system to allow the adapters to function properly. At a minimum:

  • A device needs to be created in the Auth --> Devices collection. The device will represent the adapter, or more importantly, the device or MultiTech Conduit gateway on which the adapter is executing. The name and active key values specified in the Auth --> Devices collection will be used by the adapter to authenticate to the ClearBlade Platform or ClearBlade Edge.
  • An adapter configuration data collection needs to be created in the ClearBlade Platform system and populated with the data appropriate to the mts-io adapter. The schema of the data collection should be as follows:
Column Name Column Datatype
adapter_name string
topic_root string
adapter_settings string (json)

adapter_settings

The adapter_settings column is not used in the mtacGpioAdapter Adapter

Usage

Executing the adapter

mtacGpioAdapter -systemKey=<SYSTEM_KEY> -systemSecret=<SYSTEM_SECRET> -platformURL=<PLATFORM_URL> -messagingURL=<MESSAGING_URL> -deviceName=<DEVICE_NAME> -password=<DEVICE_ACTIVE_KEY> -adapterConfigCollectionID=<COLLECTION_ID> -logLevel=<LOG_LEVEL>

Where

systemKey

  • REQUIRED
  • The system key of the ClearBLade Platform System the adapter will connect to

systemSecret

  • REQUIRED
  • The system secret of the ClearBLade Platform System the adapter will connect to

deviceName

  • The device name the adapter will use to authenticate to the ClearBlade Platform
  • Requires the device to have been defined in the Auth - Devices collection within the ClearBlade Platform System
  • OPTIONAL
  • Defaults to mtacGpioAdapter

password

  • REQUIRED
  • The active key the adapter will use to authenticate to the platform
  • Requires the device to have been defined in the Auth - Devices collection within the ClearBlade Platform System

platformUrl

  • The url of the ClearBlade Platform instance the adapter will connect to
  • OPTIONAL
  • Defaults to http://localhost:9000

messagingUrl

  • The MQTT url of the ClearBlade Platform instance the adapter will connect to
  • OPTIONAL
  • Defaults to localhost:1883

adapterConfigCollectionID

  • REQUIRED
  • The collection ID of the data collection used to house adapter configuration data

logLevel

  • The level of runtime logging the adapter should provide.
  • Available log levels:
    • fatal
    • error
    • warn
    • info
    • debug
  • OPTIONAL
  • Defaults to info

Setup


The mtsIo adapter is dependent upon the ClearBlade Go SDK and its dependent libraries being installed. The mtsIo adapter was written in Go and therefore requires Go to be installed (https://golang.org/doc/install).

Adapter compilation

In order to compile the adapter for execution within mLinux, the following steps need to be performed:

  1. Retrieve the adapter source code
    • git clone git@github.com:ClearBlade/Multitech-MTSIO-Adapter.git
  2. Navigate to the mtsioadapter directory
    • cd MTAC-GPIO-ADAPTER
  3. Compile the adapter
    • GOARCH=arm GOARM=5 GOOS=linux go build -o mtacGpioAdapter
You can’t perform that action at this time.