Provides endpoint for authenticate related tasks, including creation and destruction of temporary session keys, and checking authentication information.
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
}
Destroy the current session
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
Retrieve authentication information, useful to validate authentication is working as expected. The value returned will be a Authentication Object
200 OK
- with Authentication Object
401 Unauthorized
- with Error Object if unauthenticated
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.
200 OK
- with Authentication Object
400 Bad Request
- with Error Object if invalid input was given
401 Unauthorized
- with Error Object when authentication failed
HTTP endpoint for working with channels
Pushes a raw message to a channel. It MUST be a object containing
the field raw
with Base64 encoded value.
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
HTTP endpoint for manipulating organization resources
Retrieves a device
from network
200 OK
- with list of Network Object's
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if device does not exists
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.
200 OK
- with list of Network Object's
400 Bad Request
- with Error Object on invalid input data
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if device does not exists
Update a device
resource
200 OK
- with list of Network Object's
400 Bad Request
- with Error Object on invalid input data
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
HTTP endpoint for querying messages
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
.
Returns a object containing fields according to Message Formats
data-encoding
- see Data Encoding
200 OK
- with list of Packet Object's
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if message was not found
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.
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>
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 ....
]
}
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
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.
A query result set can be reduced by using a series of preconditions.
The conditions takes a simple form:
:
— (equality)
!:
— (non-equality)
>:
— (greater than or equal to)
>
— (greater than)
:<
— (less than or equal to)
<
— (less than)
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
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.
data-encoding
- see Data Encoding
200 OK
- with list of Packet Object's
400 Bad Request
- with Error Object if invalid data was given
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if device or network was not found
HTTP endpoint for manipulating organization resources
Retrieves a list of all network
for the authenticated entity
200 OK
- with list of Network Object's
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
Retrieve a network
200 OK
- with Network Object
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if network was not found
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.
201 Created
- with list of Network Object's
400 Bad Request
- with Error Object if errors in input
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if any of the parent resources was not found
Update a network
200 OK
- with Network Object
400 Bad Request
- with Error Object on invalid input data
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if network was not found
HTTP endpoint for manipulating organization resources
Removes user
from organization
, revoking all access to
the organization
resources.
200 OK
- with Organization Object
400 Bad Request
- with Error Object if invalid data given
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if either user or organization was not found
409 Conflict
- with Error Object when deleting last user
Retrieves a list of all organizations
for user
200 OK
- with list of Organization Object's
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
Retrieves a organization
resource
200 OK
- with Organization Object
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if either user or organization was not found
Update a organization
resource
200 OK
- with Organization Object
400 Bad Request
- with Error Object if invalid data was given
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if either user or organization was not found
Add user
to organization
, effectively allowing user
to access
all resources under said organization
.
200 OK
- with Organization Object
400 Bad Request
- with Error Object if invalid data given
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
404 Not Found
- with Error Object if either user or organization was not found
HTTP endpoint for manipulating user object
Retrieves the current user resource
200 OK
- with User Object
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
Creates a new users
201 Created
- with User Object
400 Bad Request
- with Error Object if error in payload
403 Forbidden
- with Error Object if users already exists
Retrieves the current user resource
200 OK
- with User Object
400 Bad Request
- with Error Object if invalid data given
401 Unauthorized
- with Error Object if unauthenticated
403 Forbidden
- with Error Object if lacking permissions
{: data-path=proto.appendix
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.
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.
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
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
Forces the device to perform a reset.
See Command Format for structure of packet.
Request the calibration memory of a device. The response should be a event/calibration packet.
See Command Format for structure of packet.
Request the configuration memory of a device. The response should be a event/config packet.
See Command Format for structure of packet.
Request the DID status of a device. The response should be a event/next_receiver packet.
See Command Format for structure of packet.
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.
Request the device to generate a communication path, the response should be a event/path packet.
See Command Format for structure of packet.
Request the status of a device. The response should be a event/ima packet.
See Command Format for structure of packet.
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.
Send a serial command string to the device. Unless device.command_ack
is set to true there will be no response from the device.
data
- string with length 0..120
See Command Format for structure of packet.
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).
config
- The config object to set (see Configuration Options)
See Command Format for structure of packet.
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.
gpio.gpio_{0 - 7}
- true|false
See Command Format for structure of packet.
Configure the runtime PWM output state. Unless device.command_ack
is set to true there will be no response from the device.
pwm
- integer: 0 - 100
See Command Format for structure of packet.
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.
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
Router high-level acknowledge
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.
Gateway acknowledge
detail
- always set to ack
cmd_number
- The command number that was acknowledged
See Event Format for structure of packet.
See Event Format for structure of packet.
Response to a command/get_config command.
detail
- always set to config
config
- The configuration memory dumop (see Configuration Options)
Reports a status messages either as a timed event or a response to a command/get_status.
detail
- always set to ima
See Event Format for structure of packet.
Detected change in digital I/O.
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.
Router high-level non-acknowledge
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.
Gateway non-acknowledge
detail
- always set to nak
cmd_number
- The command number that was acknowledged
reason
- The reason the command was rejected
detail
- always set to nid
nid
- The network id of the gateway
See Event Format for structure of packet.
Response to a command/get_path command.
detail
- always set to path
path
- object with format hop => [<rssi>, <uid>]
Reports a device reset
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.
See Event Format for structure of packet.
See Event Format for structure of packet.
See Event Format for structure of packet.
Serial data received from a device.
detail
- always set to serial
data
- The serial data
block
- Sequence number for long strings
Reports a RF tamper attempt.
detail
- always set to tamper
duration
- Jamming durations in minutes
ended
- Hours since jamming ended
See Event Format for structure of 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.
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
Response to a command/get_did_status command.
detail
- always set to next_receiver
receiver
- the address of the receiver
See Event Format for structure of packet.