Packets¶

Packet Data Structure¶

A packet is a representation of sensor data generated by a device trough a driver. It may produce any number of readings using a parser.

Packets can be accessed using the API, or pushed by a websocket.

In responses, a packet looks like this:

{
  "transceived_at": "2017-07-31T12:15:18.289981Z",
  "payload_encoding": "json",
  "payload": {
    "payload": 42
  },
  "packet_type": "up",
  "meta": {"more": "data"},
  "interface_id": "cee40cb2-f58c-4ca8-ae91-4ae76cba5119",
  "inserted_at": "2017-07-31T12:15:18.289981Z",
  "id": "3e097a97-e504-4b4b-8182-ae148f2109f3",
  "device_id": "43b5dca3-e7d9-4028-9309-c26ac0c08721"
}

Key	Example	Description
`transceived_at`	`2017-07-31T12:15:18.289981Z`	Date of when the packet was sent by device or received by the platform
`id`	`3e097a97-e504-4b4b-8182-ae148f2109f3`	Unique packet ID (UUID4)
`payload_encoding`	`json`	Encoding of the packet payload. Can be `json`, `binary`, `utf8` or `none`
`payload`	`{"payload": 42}`	Payload as JSON string, binary HEX data, UTF8 string, or `null` for no value
`packet_type`	`up`	Optional type of the packet, can be `up`, `down` or any other value.
`meta`	`{}`	Freeform JSON object as string that may contain any data
`is_meta`	`false`	If packet contains only metadata. If `true` the packet will not be parsed (deprecated in 3.30.0, use `skip_parsers` instead)
`skip_parsers`	`false`	If packet contains only metadata. If `true` the packet will NOT be parsed (since 3.30.0)
`skip_rules`	`false`	If `true` the rules will be skipped (since 3.30.0)
`inserted_at`	`2017-07-31T12:15:18.289981Z`	Date of the creation to the device
`interface_id`	`cee40cb2-f58c-4ca8-ae91-4ae76cba5119`	Reference to a interface
`device_id`	`50e032fb-964f-440d-9b9a-47870667373c`	Reference to the device this packet belongs to

List Packets by Device¶

Please refer to the device documentation for listing packets by device.

List Packets by Folder¶

Please refer to the folder documentation for listing packets by folder.

API Routes¶

Show a Packet for Device¶

Method: GET, Endpoint: /devices/:id_or_slug/packets/:packet_id

Example Requests¶

GET https://element-iot.com/api/v1/devices/my-device/packet/3e097a97-e504-4b4b-8182-ae148f2109f3?auth=46cb688e2c0b468e26e914235d4b73ea

Create a Packet for Device¶

Needed feature: api_packets_writeable

This method needs the feature "API packets writeable" enabled

Send packet to device

If you want to send a packet to a device, like a LoRaWAN DOWN frame, use the resource Create Action for Device

Method: POST, Endpoint: /devices/:id_or_slug/packets

Creating a packet will process it with the parser assigned to the device.

Example Requests¶

POST https://element-iot.com/api/v1/devices/my-device/packets?auth=46cb688e2c0b468e26e914235d4b73ea

# Minimal packet data
{
    "packet": {
        "payload_encoding": "binary",
        "payload": "CAFEBABE"
    }
}

# Maximal packet data
{
    "packet": {
        "payload_encoding": "json",
        "payload": "{\"answer\": 42}",
        "packet_type": "up",
        "meta": {"more": "data"},
        "transceived_at": "2017-07-31T12:15:18.289981Z", # If not given, current timestamp will be used
        "interface_id": "68e8e794-1abe-45d6-a63e-158ed5d611ef", # Interface needs to exist in device
        "id": "3e097a97-e504-4b4b-8182-ae148f2109f3" # Can be given to create packets with existing UUIDs
    }
}

Update a Packet for Device¶

Needed feature: api_packets_writeable

This method needs the feature "API packets writeable" enabled

Updating a packet will not process it with the parser assigned to the device.

Method: PUT, Endpoint: /devices/:id_or_slug/packets/:packet_id

Example Requests¶

PUT https://element-iot.com/api/v1/devices/my-device/packets?auth=46cb688e2c0b468e26e914235d4b73ea

# Same as for creating packet.
# Can not change packet id, inserted_at, or device association.

Delete a Packet for Device¶

Needed feature: api_packets_writeable

This method needs the feature "API packets writeable" enabled

Method: DELETE, Endpoint: /devices/:id_or_slug/packets/:packet_id

If readings created from the packet should be deleted, use the query parameter &remove_readings=true.

Example Requests¶

DELETE https://element-iot.com/api/v1/devices/my-device/packets?auth=46cb688e2c0b468e26e914235d4b73ea

DELETE https://element-iot.com/api/v1/devices/my-device/packets?auth=46cb688e2c0b468e26e914235d4b73ea&remove_readings=true