Message Formats

Learn how to speak the language of The Tentacle.

One of the biggest goals of The Tentacle (and Meshblu in general!) is to make it as easy as possible to talk to it.

As such, we maintain a github repo for the express purpose of defining the message and configuration schemas in JSON and Google's Protocol Buffer format.

This repo should always be checked first before using any of these examples - It is always up to date, whereas the documentation may not be!

The Tentacle has been primarily developed for use in Meshblu, though it can definitely be used without it. As such, some of the code below may be Meshblu-specific.

📘

Usage Examples

the "usage" after the examples assume you're using our command-line utility, meshblu-util. Any other method of communicating with Meshblu will work - it's just easier to do it this way.

Example Message and Configuration

The following are JSON examples that The Tentacle can understand.

🚧

Send The Tentacle a Correctly Formatted Message!

If a message fails to follow the schema below, Meshblu will rudely disconnect the microcontroller. This is to prevent the microcontroller from losing it's mind when it tries to parse an invalid format.

Example Message:

example-message

{
  "devices": "ff12c403-04c7-4e63-9073-2e3b1f8e4450",
  "payload": {
    "pins": [
      { "action" : "analogRead", "number": 16},
      { "action" : "digitalWrite", "number": 13, "value": 1}
    ]
  },
  "customData" : "You can put whatever you want here! Or nothing! The world's your oyster."
}

Usage: meshblu-util message -u -f ./message.json ./subscriber.json

Example Configuration:

📘

Serial Port Configuration

"port" is only needed if The Tentacle is used over serial. This can be accomplished with this github repo or by using it like any other Gateblu plugin.

JSON

{
  "options": {
    "port" : "/dev/tty.usbmodem14110000.1",
    "broadcastPins" : true,
    "broadcastInterval": 2500,
    "pins": [
      {"action" : "digitalWrite", "number" : 7},
      {"action" : "analogRead", "number" : 15}
    ]
  }
}

Usage: meshblu-util update -f ./configuration.json ./example-meshblu.json

JSON Schema, for the Schema Enthusiasts

Messaging:

messaging-schema

{
  "type": "object",
  "required": [
    "pins"
  ],
  "properties": {
    "customData" : {
      "type": "string"
    },
    "pins": {
     "title": "Pin Configuration",
      "type": "array",
      "default": [],
      "items": {
        "type": "object",
        "properties": {
          "number": {
            "title": "Number",
            "type": "integer",
            "minimum": 0,
            "default": 13
          },
          "action": {
            "title": "Action",
            "type": "string",
             "enum": [
              "digitalRead" ,
              "digitalWrite" ,
              "analogRead",
              "analogWrite",
              "servoWrite",
              "pwmWrite",
              "i2cWrite",
              "i2cRead"
               ]
          },
          "value": {
            "type": "integer",
            "default": 1
          }
        },
        "required": [
          "number",
          "action"
        ]
      }
    }
  }
}

Configuration:

configuration-schema

{
  "type": "object",
  "required": [
    "pins"
  ],
  "properties": {
    "pins": {
     "title": "Pin Configuration",
      "type": "array",
      "default": [],
      "items": {
        "type": "object",
        "properties": {
          "number": {
            "title": "Number",
            "type": "integer",
            "minimum": 0
          },
          "action": {
            "title": "Action",
            "type": "string",
             "enum": [
              "digitalRead" ,
              "digitalWrite" ,
              "analogRead",
              "analogWrite",
              "servoWrite",
              "pwmWrite",
              "i2cWrite",
              "i2cRead",
              "ignore"
               ]
          }
        },
        "required": [
          "number",
          "action"
        ]
      }
    },
    "broadcastPins" : {
      "title" : "Broadcast Pins?",
      "type": "boolean",
      "default": false
    },
    "broadcastInterval" : {
      "title" : "Broadcast Interval (ms)",
      "type" : "number",
      "default" : 2000,
      "minimum": 15
    }
  }
}