Authentication

Provides endpoint for authenticate related tasks, including creation and destruction of temporary session keys, and checking authentication information.

Authentication Object

The authentication object returned. The key parameter will only be present on the initial call to /auth/session, not to any calls to /auth.

{
   "type" : The type of entity used for authentication, either user or organization
   "owner" : The entity the request was authenticated as, either a organization or user id (see type)
   "resources" : A list of resources in the form `<type>/<entity>`
   "ttl" : (maybe) The expiration date for a key
   "fingerprint" : (maybe) The key fingerprint, only for key based authentication
   "key" : (maybe) The key to use for a session
}

DELETE /auth/session

Destroy the current session

Return

  • 205 Reset Content - when session was destroyed
  • 400 Bad Request - with Error Object if a non-session based key was used
  • 401 Unauthorized - with Error Object when authentication failed

GET /auth

Retrieve authentication information, useful to validate authentication is working as expected. The value returned will be a Authentication Object

Return

POST /auth/session

Create a session key for a user, the authentication happens either by using HTTP Basic authentication or by providing an object with the keys email and password.

The key expires 3600 after last use.

Return

Channels

HTTP endpoint for working with channels

POST /channel/:network/:channel

Pushes a raw message to a channel. It MUST be a object containing the field raw with Base64 encoded value.

Return

  • 202 Accepted - with no content
  • 400 Bad Request - with Error Object if input was invalid
  • 401 Unauthorized - with Error Object if unauthenticated
  • 403 Forbidden - with Error Object if lacking permissions
  • 404 Not Found - with Error Object if network or channel was not available

Devices

HTTP endpoint for manipulating organization resources

GET /device/:network/:device

Retrieves a device from network

Return

POST /device/:network

Creates a new device under network.

Returns the new object with it's path in location header. If there was a conflict the location of the existing device will be returned in the location header.

By default a device ID is automatically generated for you by the cloud service. If you do not wish this you can control this option by specifying the key parameter you desire when you are creating the device.

Return

PUT /device/:network/:device

Update a device resource

Return

Messages

HTTP endpoint for querying messages

Data Encoding

For all of the endpoints that returns packet the encoding of binary payloads can be selected by using the X-Data-Encoding header or the &data-encoding query parameter.

The option takes an enum value binary|hex|base64. The default being base64.

GET /message/:network+:device

Returns a object containing fields according to Message Formats

Options

Return

GET /message-query/:network/[:device-selector]

Performs a query in :network, possibly limited by :device-selector. The call either returns chunked HTTP response where each individual packet is returned as chunk, or a structure containing query metadata and results.

Use of `:device-selector`

The device selector may be used to limit the devices queried to either a single device, list of devices or all devices matching a equality check.

# Query all devices in a network
GET https://cloud.tiny-mesh.com/api/message-query/PG3?<queryparams>

# Query a single devices (`:device-selector` = <network>/<deviceid>`)
GET https://cloud.tiny-mesh.com/api/message-query/PG3/1RnbaX9?<queryparams>

# Query using a comma spearted list of devices (`:device-selector` = # <network>/<dev1>,<dev2>,..`)
GET https://cloud.tiny-mesh.com/api/message-query/PG3/1RnbaX9,YWiMHj3?<queryparams>

# Query devices matching a precond (`:device-selector` = # # <network>/<key>:<value>`)
# `<key>` may be any one field in `devicemap.<device>.*`. found in a network
GET https://cloud.tiny-mesh.com/api/message-query/PG3/type:gateway?<queryparams>

Example of query structure

On non-streaming queries the following structure is returned.

{
   "meta" : {
      "date" : {
         "to" : "2014-11-12T00:00:00.0000000Z",
         "from" : "2014-11-13T00:00:00.0000000Z",
         "diff" : 86400
      },
      "query" : {
         "next" : {
           "date.to" : "2014-11-13T00:00:00.0000000Z",
           "date.from" : "2014-11-14T00:00:00.0000000Z",
         },
         "prev" : {
           "date.to" : "2014-11-10T00:00:00.0000000Z",
           "date.from" : "2014-11-11T00:00:00.0000000Z",
         }
      },
      "conditions" : [],
      "objects" : 1433
   },
   "result" : [
      // result set ....
    ]
}

Parameters

  • date.from - a Date Field value specify start of query time range
  • date.to - a Date Field value specify end of query time range
  • filter.pick - A comma separated list of keys to include from the Packet Object results
  • filter.omit - A comma separated list of keys to exclude from the Packet Object results
  • limit - An integer specifying the number of results to return
  • sort.key - The key to sort by, deep values can be specified by using . as separator, ie: proto/tm.packet_num (default: datetime)
  • sort.reverse - true|false if the result set should be reversed
  • query - A comma separated list of Query Preconditions
  • stream - a comma separated list of Channels to stream from. If non empty the HTTP response will be chunked with each message delivered as a chunk.
  • accept - Accept value, as specified by HTTP spec
  • authorization - Authorization value, as specified by HTTP spec
  • data-encoding - see Data Encoding

Date field

The Date field is used to select a date time based on some simple constructs. The field expects input formatted as ISO 8601 dates or the string literal NOW which represents the current server time.

The date field can be manipulate by adding or subtracting time, the constructs can be chained together by using // for separation.

The following commands are supported:

  • //+?[N][UNIT] add [UNIT] of time where [N] is an integer.
  • //-[N][UNIT] subtract [UNIT] of time where [N] is an integer.

Unit can be one of the following: YEAR, MONTH, WEEK, DAY, HOUR, MINUTE, or SECOND.

Example: 2014//+1MONTH//-1WEEK, specifies the start last week of January 2014

All dates are expected to be UTC dates. There is no plan to add support for timezones.

Query conditions

A query result set can be reduced by using a series of preconditions. The conditions takes a simple form: where the can be one of:

  • : — (equality)
  • !: — (non-equality)
  • >: — (greater than or equal to)
  • > — (greater than)
  • :< — (less than or equal to)
  • < — (less than)

Return

  • 200 OK - with object containing query metadata and a list of Packet Object's
  • 400 Bad Request - with Error Object on bad query terms
  • 401 Unauthorized - with Error Object if unauthenticated
  • 403 Forbidden - with Error Object if lacking permissions

POST /message/:network/:device

Create a new message for the device specified. The structure of the message must be as defined in Packet Formats. Values like uid and sid are automatically set by the system, whilst package_num can optionally be specified. All other parameters are required.

Creating events from the API is discouraged for all other purposes than federating data.

Options

Return

Networks

HTTP endpoint for manipulating organization resources

GET /network

Retrieves a list of all network for the authenticated entity

Return

GET /network/:network

Retrieve a network

Return

POST /network

Creates a new network object, payload should contain a minimal Network Object but may be empty.

Special care must be taken using the parents property. If the parents property is not defined it will use data derived from the authentication information (if authenticated as user, user/:email will be added, if authenticated as organization organization/:org will be added). Otherwise any combination user or clients that the current user have access to may be specified.

Return

PUT /network/:network

Update a network

Return

Organizations

HTTP endpoint for manipulating organization resources

DELETE /organization/:organization/user/:user

Removes user from organization, revoking all access to the organization resources.

Return

GET /organization

Retrieves a list of all organizations for user

Return

GET /organization/:organization

Retrieves a organization resource

Return

PUT /organization/:organization

Update a organization resource

Return

PUT /organization/:organization/user/:user

Add user to organization, effectively allowing user to access all resources under said organization.

Return

User

HTTP endpoint for manipulating user object

GET /user

Retrieves the current user resource

Return

POST /user/register

Creates a new users

Return

PUT /user

Retrieves the current user resource

Return

Tiny Mesh Protocol

Appendix

{: data-path=proto.appendix

Command Format

Outgoing commands share a common base format containing things like command number and the target device UID.

If the Tiny Mesh Cloud service is used the UID and packet number will be dictated by the API.

Fields

  • uid - The unique id of the Tiny Mesh Network
  • type - Always set to command
  • command - The type of command issued
  • cmd_number - The command number used, returned by ACK's and NAK's events.

Event Header

All event messages contain some header information. These field can be used to gather some metrics about changes in network and quality of message delivery.

See also: Generic Event Packet

Fields

  • sid - The system id of the Tiny Mesh Network
  • uid - The unique id of the Tiny Mesh Network
  • rssi - The signal strength to the neighbouring node
  • network_lvl - The hop level the device is located at
  • hops - The number of hops the packet have traversed
  • packet_number - The id of the packet generated by the device
  • latency - The time packet have been in the RF network before delivery
  • type - Always set to event
  • detail - The type of event received

Commands

command/force_reset

Forces the device to perform a reset.

See Command Format for structure of packet.

command/get_calibration

Request the calibration memory of a device. The response should be a event/calibration packet.

See Command Format for structure of packet.

command/get_config

Request the configuration memory of a device. The response should be a event/config packet.

See Command Format for structure of packet.

command/get_did_status

Request the DID status of a device. The response should be a event/next_receiver packet.

See Command Format for structure of packet.

command/get_nid

Request the network id of a gateway. The response should be a event/nid packet. If the device is not a gateway the response is undefined.

See Command Format for structure of packet.

command/get_path

Request the device to generate a communication path, the response should be a event/path packet.

See Command Format for structure of packet.

command/get_status

Request the status of a device. The response should be a event/ima packet.

See Command Format for structure of packet.

command/init_gw_config

Sets a gateway in configuration mode. If the device is not a gateway the response from the device is undefined.

See Command Format for structure of packet.

command/serial

Send a serial command string to the device. Unless device.command_ack is set to true there will be no response from the device.

Fields:

  • data - string with length 0..120

See Command Format for structure of packet.

command/set_config

Send a over the air configuration update. The device MAY respond with a event/ack or event/nak packet. before a event/reset packet is received (indicating a successful config change).

Fields

See Command Format for structure of packet.

command/set_output

Configure the runtime state of one or more digital pins. Unless device.command_ack is set to true there will be no response from the device.

Fields

  • gpio.gpio_{0 - 7} - true|false

See Command Format for structure of packet.

command/set_pwm

Configure the runtime PWM output state. Unless device.command_ack is set to true there will be no response from the device.

Fields

  • pwm - integer: 0 - 100

See Command Format for structure of packet.

Configuration Options

Note: This documentation was generated for version 1.41". If your version of the firmware is newer, look for the updated version of this documentation at the bottom of this page.

Parameters

  • rf.mac_rnd_mask_2 - enum: 116, 63, 31, 15, 7, 3 (since: 1.38)
  • rf.mac_rnd_mask_1 - enum: 116, 63, 31, 15, 7, 3 (since: 1.38)
  • net.command_retries - integer: 0..127
  • net.command_accept_time - integer: 0..255
  • group.membership - set (max size: 8 (since: 1.40)
  • pulse_counter.feedback - enum: 0, 2 (since: 1.40)
  • pulse_counter.feedback_port - enum: 0, 1, 2, 3, 4, 5, 6, 7, 255 (since: 1.40)
  • rf_jamming.port - enum: 0, 1, 2, 3, 4, 5, 6, 7, 255 (since: 1.34)
  • rf_jamming.detect - integer: 0..100 (since: 1.34)
  • device.detect_busy_network - enum: 0, 1, 2 (since: 1.20)
  • cluster.rssi_threshold - integer: 40..100 (since: 1.34)
  • cluster.device_limit - integer: 5..100 (since: 1.34)
  • net.connect_change_margin - integer: 0..255 (since: 1.37)
  • pulse_counter.debounce - integer: 0..255 (since: 1.40)
  • pulse_counter.mode - enum: 0, 1, 3 (since: 1.40)
  • device.sleep_or_rts_pin - enum: 0, 1 (since: 1.40)
  • device.command_ack - enum: 0, 1 (since: 1.20)
  • device.sniff_neighbours - enum: 0, 1 (since: 1.40)
  • device.indicators_timeout - integer: 0..255 (since: 1.40)
  • end_device.wakeon_port - enum: 0, 1, 2, 3, 4, 5, 6, 7, 255 (since: 1.40)
  • end_device.wakeon - integer: 0..15 (since: 1.40)
  • end_device.keepalive - integer: 0..255 (since: 1.40)
  • security.level - enum: 0, 1, 2 (since: 1.31)
  • device.fw_revision - string:
  • device.hw_revision - string:
  • device.part - string
  • uart.buffer_margin - integer: 0..100 (since: 1.31)
  • uart.flow_control - integer: 1..59 (since: 1.31)
  • uart.stop_bits - enum: 1, 2 (since: 1.21)
  • uart.parity - enum: 0, 1 (since: 1.21)
  • uart.bits - enum: 8, 9 (since: 1.21)
  • uart.baud_rate - enum: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
  • uart.cts_hold_time - integer: 1..255
  • gpio.input_debounce - integer: 0..255
  • gpio_7.pwm_default - integer: 0..100
  • gpio_7.trigger - enum: 0, 1, 2, 3
  • gpio_7.config - enum: 0, 1, 3, 4
  • gpio_6.trigger - enum: 0, 1, 2, 3
  • gpio_6.config - enum: 0, 1, 4
  • gpio_5.trigger - enum: 0, 1, 2, 3
  • gpio_5.config - enum: 0, 1, 4
  • gpio_4.trigger - enum: 0, 1, 2, 3
  • gpio_4.config - enum: 0, 1, 4
  • gpio_3.trigger - enum: 0, 1, 2, 3
  • gpio_3.config - enum: 0, 1, 4
  • gpio_2.trigger - enum: 0, 1, 2, 3
  • gpio_2.config - enum: 0, 1, 4
  • gpio_1.analogue_sample_rate - integer: 0..255
  • gpio_1.analogue_low_trig - integer: 0..2047
  • gpio_1.analogue_high_trig - integer: 0..2047
  • gpio_1.trigger - enum: 0, 1, 2, 3
  • gpio_1.config - enum: 0, 1, 2, 4
  • gpio_0.analogue_sample_rate - integer: 0..255
  • gpio_0.analogue_low_trig - integer: 0..2047
  • gpio_0.analogue_high_trig - integer: 0..2047
  • gpio_0.trigger - enum: 0, 1, 2, 3
  • gpio_0.config - enum: 0, 1, 2, 4
  • net.excellent_rssi - integer: 0..255 (since: 1.37)
  • device.sid - integer: 0..4294967295
  • device.uid - integer: 0..4294967295
  • device.locator - enum: 0, 1
  • device.type - enum: 1, 2
  • device.type - enum: 1, 2, 3 (since: 1.40)
  • device.protocol_mode - enum: 0, 1
  • uart.timeout - integer: 1..255
  • net.tx_retry_limit - integer: 1..255
  • net.max_packet_latency - integer: 1..255
  • net.max_jump_count - integer: 1..255
  • net.max_jump_level - integer: 1..255
  • net.connect_check_time - integer: 4..20
  • ima.trig_hold - integer: 0..255 (since: 1.40)
  • ima.address_field - enum: 0, 1, 2, 3 (since: 1.40)
  • ima.data_field - enum: 0, 1, 2 (since: 1.40)
  • ima.on_connect - enum: 0, 1
  • ima.time_base - integer: 1..255
  • ima.time - integer: 1..255
  • net.hiam_time - integer: 1..10
  • net.rssi_cc_assesment - integer: 100..210
  • net.rssi_threshold - integer: 160..210
  • rf.data_rate - integer: 1..6
  • rf.power - integer: 1..5
  • rf.channel - integer: 1..83

Events

event/ack (router)

Router high-level acknowledge

Fields

  • detail - always set to ack
  • cmd_number - The command number that was acknowledged
  • reason - The reason the command was rejected

See Event Format for structure of packet.

event/ack (gateway)

Gateway acknowledge

Fields

  • detail - always set to ack
  • cmd_number - The command number that was acknowledged

event/aio0_change

See Event Format for structure of packet.

event/aio1_change

See Event Format for structure of packet.

event/config

Response to a command/get_config command.

Fields:

event/ima

Reports a status messages either as a timed event or a response to a command/get_status.

Fields:

  • detail - always set to ima

See Event Format for structure of packet.

event/io_change

Detected change in digital I/O.

Fields

  • detail - always set to io_change
  • locator - The id of closest locator (if any)
  • triggers - Map of GPIO pins triggered

See Event Format for structure of packet.

event/nak (router)

Router high-level non-acknowledge

Fields

  • detail - always set to nak
  • cmd_number - The command number that was acknowledged
  • reason - The reason the command was rejected

See Event Format for structure of packet.

event/nak (gateway)

Gateway non-acknowledge

Fields

  • detail - always set to nak
  • cmd_number - The command number that was acknowledged
  • reason - The reason the command was rejected

event/nid

Fields

  • detail - always set to nid
  • nid - The network id of the gateway

See Event Format for structure of packet.

event/path

Response to a command/get_path command.

Fields:

  • detail - always set to path
  • path - object with format hop => [<rssi>, <uid>]

event/reset

Reports a device reset

Fields:

  • detail - always set to reset
  • trigger - The reason for the reset power|pin|sleep_or_config|command|watchdog

See Event Format for structure of packet.

See Event Format for structure of packet.

event/rfchannel_jammed

See Event Format for structure of packet.

event/rfchannel_shared

See Event Format for structure of packet.

event/rfchannel_taken

See Event Format for structure of packet.

event/rfchannel_free

event/serial

Serial data received from a device.

Fields:

  • detail - always set to serial
  • data - The serial data
  • block - Sequence number for long strings

event/tamper

Reports a RF tamper attempt.

Fields:

  • detail - always set to tamper
  • duration - Jamming durations in minutes
  • ended - Hours since jamming ended

See Event Format for structure of packet.

Generic Event Packet

In addition to the Event Header a lot of status messages contain the current state of the device, possibly with some added information. The fields are documented below.

Fields

  • detail - The type of event received
  • data - 0 if not otherwise specified
  • locator - The id of closest locator, if any (optional)
  • temp - The core temperature of the RF module
  • temp - The core temperature of the RF module in Celsius
  • volt - The voltage/battery monitor
  • dio - object containing digital i/o state
  • aio0 - The analogue input ping #0
  • aio1 - The analogue input pin #0
  • hw - The hardware revision
  • fw - The firmware revision

event/next_receiver

Response to a command/get_did_status command.

Fields:

  • detail - always set to next_receiver
  • receiver - the address of the receiver

See Event Format for structure of packet.