clearblade/socket_listener_adapter repository overview

The socket_listener_adapter adapter provides the ability for the ClearBlade Platform or ClearBlade Edge to receive data over a tcp or udp socket.

The adapter subscribes to MQTT topics which are used to interact with the socket. The adapter publishes any data received from the socket to MQTT topics so that the ClearBlade Platform/Edge is able to process the data as needed.

⁠MQTT Topic Structure

The socket_listener_adapter adapter utilizes MQTT messaging to communicate with the ClearBlade Platform. The adapter will publish messages to MQTT topics in order to send socket data to the ClearBlade Platform/Edge. The topic structures utilized by the adapter are as follows:

• {TOPIC ROOT}/{PROTOCOL}/{LISTENER PORT}/incoming-data

⁠ClearBlade Platform Dependencies

The socket-listener-adapter 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 Septentrio GNSS receiver or the 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 socket-listener-adapter installation. The schema of the data collection should be as follows:

where

⁠adapter_name = socket-listener-adapter

⁠topic_root = The root level MQTT topic the adapter should publish to, ex socket-listener

⁠adapter_settings

The adapter_settings column will need to contain an array of JSON objects containing the following attributes:

⁠protocol

• Either tcp or udp

⁠listen_port

• The tcp/udp port the adapter should connect to

⁠message_end_character

• The protocol specific character used to terminate the data stream

⁠transform_to_hex

• A boolean flag indicating whether or not the received data should be transformed to hex

⁠adapter_settings_examples

⁠TCP connection type example

[
  {
    "protocol": "tcp",
    "listen_port": "64010",
    "message_end_character": "\n"
  },
  {
    "protocol": "tcp",
    "listen_port": "64011",
    "message_end_character": "\n"
  },
  {
    "protocol": "udp",
    "listen_port": "2018",
    "message_end_character": "\n",
    "transform_to_hex": true
  }
]

⁠Executing the adapter

docker run -d --name socket_listener_adapter --network cb-net --restart always socket_listener_adapter -systemKey=<SYSTEM_KEY> -systemSecret=<SYSTEM_SECRET> -platformURL=<PLATFORM_URL> -messagingURL=<MESSAGING_URL> -deviceName=<DEVICE_NAME> -password=<DEVICE_ACTIVE_KEY> -adapterConfigCollection=<COLLECTION_NAME> -logLevel=<LOG_LEVEL>

-systemKey The System Key of your System on the ClearBlade Platform
-systemSecret The System Secret of your System on the ClearBlade Platform
-platformURL The address of the ClearBlade Platform (ex. https://platform.clearblade.com:443)
-messagingURL The MQTT broker address (ex. tcp://platform.clearblade.com:1883)
-deviceName The name of a device account created on the ClearBlade Platform
-password The active key of a device created on the ClearBlade Platform
-logLevel The level of runtime logging the adapter should provide (fatal, error, warn, info, debug)