Skip to content

doc: Add attributes to uplink message data format #1397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vlasebian merged 1 commit into from
Jan 29, 2025
Merged

doc: Add attributes to uplink message data format #1397

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 24 additions & 17 deletions doc/content/integrations/data-formats/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ These message are closely related to LoRaWAN® message types. Read more about th

{{< note >}} Empty fields are omitted from payloads. As such, if a certain field has a value of `""`, `0` or `false` it will not be present in the message. {{</ note >}}

{{< new-in-version "v3.34.0" >}} Uplink messages forward the attributes of the end device that produced the message.

### Join-accept Messages

The JSON join-accept messages use the following format:
Expand All @@ -37,7 +39,11 @@ The JSON join-accept messages use the following format:
"received_at" : "2020-02-12T15:15..." // ISO 8601 UTC timestamp at which the message has been received by the Application Server
"join_accept" : {
"session_key_id" : "AXBSH1Pk6Z0G166...", // Join Server issued identifier for the session keys
"received_at" : "2020-02-17T07:49..." // ISO 8601 UTC timestamp at which the uplink has been received by the Network Server
"received_at" : "2020-02-17T07:49...", // ISO 8601 UTC timestamp at which the uplink has been received by the Network Server
"attributes": { // End device key-value attributes set for this device.
"key1": "value1",
"key2": "value2"
}
}
}
```
Expand All @@ -62,10 +68,14 @@ The JSON join-accept messages use the following format:
"ns:uplink:01E191YMZ2J64K6FEW5F0WE7TQ",
"rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01E191YMZ2KK3TJYG5C4XZP8JK"
],
"received_at": "2020-02-17T07:49:09.935284891Z",
"join_accept": {
"session_key_id": "AXBSH1Pk6Z0G166RlH16CQ==",
"received_at": "2020-02-17T07:49:09.736532315Z"
"received_at" : "2020-02-17T07:49:09.935284891Z",
"join_accept" : {
"session_key_id" : "AXBSH1Pk6Z0G166RlH16CQ==",
"received_at" : "2020-02-17T07:49:09.736532315Z",
"attributes": {
"key1": "value1",
"key2": "value2"
}
}
}
```
Expand Down Expand Up @@ -148,6 +158,10 @@ The JSON uplink messages use the following format:
"net_id": "000013", // Network ID
"tenant_id": "tenant1", // Tenant ID
"cluster_id": "eu1" // Cluster ID
},
"attributes": { // End device key-value attributes set for this device.
"key1": "value1",
"key2": "value2"
}
},
"simulated": true, // Signals if the message is coming from the Network Server or is simulated.
Expand Down Expand Up @@ -231,23 +245,16 @@ The JSON uplink messages use the following format:
"tenant_id": "tenant1",
"cluster_id": "nam1"
},
"received_at": "2020-02-12T15:15:45.789585559Z"
"attributes": {
"key1": "value1",
"key2": "value2"
}
"received_at" : "2020-02-12T15:15:45.789585559Z"
}
}
```

</details>

{{< note >}} End device key-value attributes are not included in uplink messages, because these attributes are stored in the Identity Server and normally they are static, so sending that data with every uplink is inefficient. Users can instead fetch device's attributes using the API:

```bash
curl --request GET /
--location 'https://thethings.example.com/api/v3/applications/<application-id>/devices/<device-id>?field_mask=attributes' /
--header "Authorization: Bearer <api-key>"
```

{{</ note >}}

### Downlink Events Messages

The JSON downlink `ack`, `nack`, `queued` and `sent` events messages use the following format:
Expand Down
Loading