Skip to content

Commit 0fc9247

Browse files
addshoreaddshore
committed
Rework the device API, protocol and message page layouts
1 parent 51933cb commit 0fc9247

File tree

19 files changed

+988
-576
lines changed

19 files changed

+988
-576
lines changed

‎.vitepress/config.mts

Lines changed: 31 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -291,34 +291,49 @@ export default withMermaid(defineConfig({
291291
link: '/devices/api/glossary',
292292
},
293293
{
294-
text: 'Structure',
294+
text: 'Toit',
295+
link: '/devices/api/sdks/toit/',
296+
items: [
297+
{ text: 'Getting Started', link: '/devices/api/sdks/toit/getting-started' },
298+
{
299+
text: 'Examples',
300+
link: '/devices/api/sdks/toit/examples/',
301+
},
302+
],
303+
},
304+
{
305+
text: 'Messages',
295306
collapsed: true,
296-
link: '/devices/api/structure',
307+
link: '/devices/api/messages',
308+
items: protocolMenuItems,
309+
},
310+
{
311+
text: 'Protocol',
312+
collapsed: true,
313+
link: '/devices/api/protocol/',
297314
items: [
298315
{
299316
text: 'Prefix',
300-
link: '/devices/api/structure#prefix',
317+
link: '/devices/api/protocol/prefix',
318+
},
319+
{
320+
text: 'Stop',
321+
link: '/devices/api/protocol/stop',
301322
},
302323
{
303-
text: 'Message',
304-
link: '/devices/api/structure#message',
324+
text: 'Structure',
325+
link: '/devices/api/protocol/structure',
326+
},
327+
{
328+
text: 'Headers',
329+
link: '/devices/api/protocol/headers',
305330
},
306331
{
307332
text: 'Examples',
308-
link: '/devices/api/structure#examples',
333+
link: '/devices/api/protocol/examples',
309334
},
310335
]
311336
},
312-
{
313-
text: 'Headers',
314-
link: '/devices/api/headers',
315-
},
316-
{
317-
text: 'Messages',
318-
collapsed: true,
319-
link: '/devices/api/messages',
320-
items: protocolMenuItems,
321-
},
322337
{
323338
text: 'Tools',
324339
collapsed: true,
@@ -337,26 +352,6 @@ export default withMermaid(defineConfig({
337352
},
338353
]
339354
},
340-
{
341-
text: 'SDKs',
342-
collapsed: true,
343-
items: [
344-
{
345-
text: 'Toit',
346-
link: '/devices/api/sdks/toit/',
347-
items: [
348-
{ text: 'Getting Started', link: '/devices/api/sdks/toit/getting-started' },
349-
{
350-
text: 'Examples',
351-
link: '/devices/api/sdks/toit/examples/',
352-
items: [
353-
{ text: 'EInk Hello World', link: '/devices/api/sdks/toit/examples/eink' },
354-
]
355-
},
356-
],
357-
},
358-
]
359-
},
360355
]
361356
},
362357
],

‎.vitepress/theme/Layout.vue

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ const redirects = Object.entries({
1717
'/devices/api/generate': '/devices/api/tools/generate',
1818
'/apps/admin/creating-account': '/apps/admin/authentication#creating-an-account',
1919
'/apps/admin/permissions': '/apps/admin/authentication#permissions',
20+
'/devices/api/structure': '/devices/api/protocol',
21+
'/devices/api/headers': '/devices/api/protocol/headers',
2022
})
2123
2224
watch(

‎cspell.json

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
"package-lock.json",
66
"package.json",
77
"public/device-specs/**/*.yaml",
8-
"public/swagger/v1.json"
8+
"public/swagger/v1.json",
9+
"public/files/protocol-v3.yaml"
910
],
1011
"dictionaryDefinitions": [],
1112
"dictionaries": [],
@@ -52,7 +53,20 @@
5253
"multipath",
5354
"iccid",
5455
"imei",
55-
"NTRIP"
56+
"NTRIP",
57+
"microcontroller",
58+
"UART",
59+
"HPSYS",
60+
"SPIWP",
61+
"acking",
62+
"RSSI",
63+
"actioned",
64+
"centi",
65+
"DGNSS",
66+
"NMEA",
67+
"WCDMA",
68+
"hectopascals",
69+
"codegen"
5670
],
5771
"ignoreWords": [],
5872
"import": []

‎devices/api/glossary.md

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@ outline: deep
66

77
| Term | Description |
88
| ------------------ | ----------------------------------------------------------------------- |
9-
| Message | A single message sent between hosts |
10-
| Prefix | Optional bytes before a message to make it easier to see in a byte stream. |
11-
| Header | The first part of the message that contains metadata about the message. |
12-
| Payload | The primary data that is being sent in the message. |
13-
| Header field type | A field type (uint8) that is used within header data |
14-
| Payload field type | A field type (uint8) that is used within payload data |
15-
| bBytes | A byte array that represents a length and then the data itself, such as `3 9 9 9`, where `3` is the length |
9+
| [Toit](/devices/api/sdks/toit/) | A programming language designed for IoT devices, which we provide a [high level SDK](/devices/api/sdks/toit/) for.<br>[[Toit official website](https://toitlang.org/)] |
10+
| ESP32 | A popular low-cost microcontroller with built-in WiFi and Bluetooth, used in some Lightbug devices.<br>[[ESP32 on Wikipedia](https://en.wikipedia.org/wiki/ESP32)] |
11+
| Message | A packet of communication sent between clients, using the [Lightbug protocol](/devices/api/protocol/). |
12+
| [Prefix](/devices/api/protocol/prefix) | Optional bytes before a message to make it easier to see in a byte stream.<br>`0x4c, 0x42` which is `LB` in ascii. |
13+
| Header | The first part of the message that contains metadata about a message.<br>Length, type, method, and other generic metadata or instruction. |
14+
| Payload | The primary data that is being sent in a message. |
15+
| [Header field](/devices/api/protocol/headers) type | A field type `uint8` that is used within header data.<br>These are generally reused across all message types. |
16+
| Payload field type | A field type `uint8` that is used within payload data.<br>These are generally specific to a message type.<br>See [messages](/devices/api/messages/). |
17+
| bBytes | A byte array that represents a length and that amount of data in bytes.<br>A bByte entry might be `3 9 9 9`, where `3` is the length, and `9 9 9` is the data. |

‎devices/api/headers.md

Lines changed: 0 additions & 93 deletions
This file was deleted.

‎devices/api/index.md

Lines changed: 13 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -8,38 +8,27 @@ import ProtocolBytes from '../../components/ProtocolBytes.vue';
88

99
# Device API
1010

11-
The device API makes use of the Lightbug communication protocol, also known as the V3 protocol, which is a byte oriented protocol used for device communication.
11+
The device API is a messaging system for communicating with Lightbug devices. It allows you to:
12+
- send commands to the device
13+
- ask for data (GET)
14+
- subscribe to data streams (SUBSCRIBE)
15+
- receive responses, instructions and other data from the device
1216

13-
The protocol builds on top of existing Lightbug protocols, and is designed to be:
14-
- Easy to use and understand
15-
- Efficient to read and build
16-
- Lightweight to store and transmit
17-
- Usable in a variety of settings, without complex or bloated dependencies
17+
It makes use of the Lightbug communication protocol, also known as the V3 protocol, which is a byte oriented protocol used for device communication.
1818

19-
## API Access
19+
On the wire, a single message might look like `4c 42 03 0b 00 01 00 00 00 00 00 4b be`, however, the API abstracts this away so you can work with high level messaging concepts.
2020

21-
API access depends on the device and may not be supported on all models.
21+
And you can [get started with Toit quickly](/devices/api/sdks/toit/), using an SDK built on top of the messages as another layer of abstraction.
2222

2323
Typically, it can be accessed via UART, I2C, or a UDP network connection.
2424

25-
For access details, please [contact our support team](https://lightbug.io/contact/).
2625

27-
Or you can [get started with Toit quickly](/devices/api/sdks/toit/) using the Lightbug provided SDK.
26+
## Availability
2827

29-
## Example Message
28+
Device API access depends on the device and may not be supported on all models.
3029

31-
An example [prefixed](structure#prefix) and minimal message might look as follows:
30+
The [RH2 RTK device](/devices/rtk/) will be the first general release product to support the API, with a future low cost development board planned.
3231

33-
| Format | Message |
34-
| ------ | --- |
35-
| Bytes | 76 66 3 11 0 1 0 0 0 0 0 75 190 |
36-
| Hex | `4c 42 03 0b 00 01 00 00 00 00 00 4b be` |
32+
For details, please [contact our support team](https://lightbug.io/contact/).
3733

38-
<ProtocolBytes
39-
byteString="76 66 3 11 0 1 0 0 0 0 0 75 190"
40-
:allowCollapse="false"
41-
></ProtocolBytes>
42-
43-
::: info
44-
All integers are in [little-endian](https://en.wikipedia.org/wiki/Endianness) format eg. (uint16 `1` is represented as `0x01 0x00`).
45-
:::
34+
If you have a supported device, you can [get started with Toit quickly](/devices/api/sdks/toit/) using the Lightbug SDK, or communicate with the device from other languages using the messages documented here.

‎devices/api/messages/5-ack.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ flowchart LR
3030
B -->|ACK| A
3131
```
3232

33-
The [Response Message ID](./../headers#_3-response-message-id) field in the header can be used in place of an ACK if an immediate response is being sent.
33+
The [Response Message ID](../protocol/headers#_3-response-message-id) field in the header can be used in place of an ACK if an immediate response is being sent.
3434

3535
In such cases the response will not have an ACK message type, instead it will have the message type of the response (often the same as the request).
3636

‎devices/api/messages/index.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@ import ProtocolBytes from '../../../components/ProtocolBytes.vue'
55

66
# Messages
77

8-
Messages often make use of a few common [header fields](/devices/api/headers), and you can expect to see these in most messages types:
8+
Messages often make use of a few common [header fields](/devices/api/protocol/headers), and you can expect to see these in most messages types:
99

1010
## Requests
1111

12-
Requests may or may not require a [MH 5: Method](./../headers#_5-method) header field, such as `GET`, `DO`, `SET` or `SUBSCRIBE`.
12+
Requests may or may not require a [MH 5: Method](../protocol/headers#_5-method) header field, such as `GET`, `DO`, `SET` or `SUBSCRIBE`.
1313

1414
This is decided by the individual message type, and if required, should be included in the header.
1515

@@ -19,11 +19,11 @@ This is decided by the individual message type, and if required, should be inclu
1919

2020
You should receive a response to every valid and expected message when the recipient is able to process the request.
2121

22-
When a message ID is provided in the request, any direct response should include the initiating message ID in the header [MH 3: Response Message ID](./../headers#_3-response-message-id).
22+
When a message ID is provided in the request, any direct response should include the initiating message ID in the header [MH 3: Response Message ID](../protocol/headers#_3-response-message-id).
2323

2424
Responses can come in the form of a basic [MT 5: ACK](./5-ack) or as the same message type as the request.
2525

26-
Responses should contain a [MH 4: Response Status](./../headers#_4-response-status) in the header, where 0 and below are various OK responses, and anything higher than 0 indicates a warning or error.
26+
Responses should contain a [MH 4: Response Status](../protocol/headers#_4-response-status) in the header, where 0 and below are various OK responses, and anything higher than 0 indicates a warning or error.
2727

2828
## Types
2929

‎devices/api/protocol/examples.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
outline: [2,3]
3+
---
4+
5+
<script setup>
6+
import ProtocolBytes from '../../../components/ProtocolBytes.vue';
7+
</script>
8+
9+
# Examples
10+
11+
### Type 3, header empty, data empty
12+
13+
<ProtocolBytes
14+
byteString="3 11 0 1 0 0 0 0 0 75 190"
15+
:defaultCollapsed="true"
16+
></ProtocolBytes>
17+
18+
### .. as above, with LB prefix bytes:
19+
20+
<ProtocolBytes
21+
byteString="76 66 3 11 0 1 0 0 0 0 0 75 190"
22+
:defaultCollapsed="true"
23+
></ProtocolBytes>
24+
25+
### Type 6, header (1:1), data empty
26+
27+
<ProtocolBytes
28+
byteString="3 14 0 6 0 1 0 1 1 1 0 0 217 95"
29+
:defaultCollapsed="true"
30+
></ProtocolBytes>
31+
32+
### Type 6, header (1:9), data empty
33+
34+
<ProtocolBytes
35+
byteString="3 14 0 6 0 1 0 1 1 9 0 0 120 246"
36+
:defaultCollapsed="true"
37+
></ProtocolBytes>
38+
39+
### Type 10009, header empty, data (10:hello):
40+
41+
<ProtocolBytes
42+
byteString="3 18 0 25 39 0 0 1 0 10 5 104 101 108 108 111 118 77"
43+
:defaultCollapsed="true"
44+
></ProtocolBytes>

0 commit comments

Comments
 (0)