Intro to device messaging changes

Author: addshore

devices/api/index.md

@@ -8,21 +8,28 @@ import ProtocolBytes from '../../components/ProtocolBytes.vue';
 
 # Device API
 
-The device API is a messaging system for communicating with Lightbug devices. It allows you to:
+The device API is a messaging system for communicating with Lightbug devices. It allows you to send and receive [messages](/devices/api/messages/) to and from the device, enabling control and data exchange.
+
+It makes use of the [Lightbug communication protocol](/devices/api/protocol/), which is a byte oriented protocol used for device communication.
+
+This documentation focuses  on the higher level element of this API first, including the [Toit SDK](/devices/api/sdks/toit/), before working its was down to the [message level](/devices/api/messages/), and finally the [protocol level](/devices/api/protocol/) which underpins it all.
+
+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.
+
+## Capabilities
+
+The Device API allows you to:
  - send commands to the device
  - ask for data (GET)
  - subscribe to data streams (SUBSCRIBE)
  - receive responses, instructions and other data from the device
 
-It makes use of the Lightbug communication protocol, also known as the V3 protocol, which is a byte oriented protocol used for device communication.
-
 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.
 
-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.
+## Accessability
 
 Typically, it can be accessed via UART, I2C, or a UDP network connection.
 
-
 ## Availability
 
 Device API access depends on the device and may not be supported on all models.

devices/api/messages/5-ack.md

@@ -11,12 +11,6 @@ import PayloadTable from '../../../components/PayloadTable.vue'
 import HeaderTable from '../../../components/HeaderTable.vue'
 </script>
 
-::: danger ⚠️ Not yet public
-The Device API currently in development and is not yet accessible on production devices.
-
-These pages can be seen as a view of what is to come later this year.
-:::
-
 # 5: ACK
 
 <SplitColumnView>

devices/api/messages/index.md

@@ -5,30 +5,58 @@ import ProtocolBytes from '../../../components/ProtocolBytes.vue'
 
 # Messages
 
-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:
+Messages are the core building blocks of the protocol, allowing you to send and receive data and commands to and from devices.
 
-## Requests
+All messages follow a common structure, but each type of message has its own specific purpose, payload, requirements and usage.
 
-Requests may or may not require a [MH 5: Method](../protocol/headers#_5-method) header field, such as `GET`, `DO`, `SET` or `SUBSCRIBE`.
+## Types
 
-This is decided by the individual message type, and if required, should be included in the header.
+Messages all have a type, represented as a `uint16` value, which defines the structure and purpose of the message, including what headers and payload it may or should contain.
 
+Some example message types for the device API include:
+- [13: Heartbeat](./13-heartbeat) - A simple message to indicate the communication link is alive
+- [34: Device Status](./34-device-status) - A message containing various status information about the device
+- [10011: Draw Element](./10011-draw-element) - A message to draw a shape on the device's display
+- ...
 
+You can find complete documentation for the messages used as part of the device API in the sidebar of this page.
 
-## Responses
+Values of `60,000` to `61,000` are currently reserved for custom use. Feel free to implement your own messages within this range.
 
-You should receive a response to every valid and expected message when the recipient is able to process the request.
+## Header fields
 
-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).
+Messages make use of a few common [header fields](/devices/api/protocol/headers) that are defined at the protocol level that you'll likely want to familiarize yourself with as they are used in device messaging.
 
-Responses can come in the form of a basic [MT 5: ACK](./5-ack) or as the same message type as the request.
+Such as:
+- [1: Message ID](../protocol/headers#_1-message-id) for uniquely identifying messages
+- [3: Response to](../protocol/headers#_3-response-to) for linking responses to requests
+- [4: Status](../protocol/headers#_4-status) for indicating the status of a message
+- [5: Method](../protocol/headers#_5-method) for optionally specifying the action to be taken
 
-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.
+You can find the full list of header fields in the [Headers documentation](/devices/api/protocol/headers) for the protocol.
 
-## Types
+### Methods
+
+A method is an optional header field that can be included in messages, and is sometimes used throughout the device API.
+
+Currently defined methods are:
+- `1: SET` - Set a value or state on the device
+- `2: GET` - Get a value or state from the device
+- `3: SUBSCRIBE` - Subscribe to updates for a value or state on the device
+- `5: UNSUBSCRIBE` - Unsubscribe from updates for a value or state on the device
 
-Per the specification, message types are represented by a single `uint16` value.
+You can find more information about these methods in the [MH 5: Method](../protocol/headers#_5-method) section.
 
-Values of `60,000` to `61,000` are currently reserved for custom use.
+## Communication patterns
+
+You should receive a response to every valid and expected message when the recipient is able to process the request.
+
+When your message includes a [MH 1: Message ID](../protocol/headers#_1-message-id), the response should include the same message ID in the [MH 3: Response to](../protocol/headers#_3-response-to) header field.
+
+:::warning
+If you do not include a message ID, you may not receive a response
+:::
+
+Responses can come in the form of a basic [MT 5: ACK](./5-ack) or as the same message type as the request.
 
-Feel free to implement your own messages within this range.
+Responses can contain a [MH 4: Response Status](../protocol/headers#_4-message-status) in the header, where 0 and below are various OK responses, and anything higher than 0 indicates a warning or error.

devices/api/protocol/headers.md

@@ -10,7 +10,7 @@ import GenerateConsts from '../../../components/GenerateConsts.vue'
 
 These header field types are reserved across all message types and usages of the protocol.
 
-<GenerateConsts :dataName="'MH'" :dataPath="'header'"/>
+For use in code, you can find a code generation section at the [bottom of this page](#code-generation).
 
 ## 1: Message ID
 
@@ -124,3 +124,7 @@ Reserved for future use.
 ## 16: Message Level
 
 Reserved for future use.
+
+## Code generation
+
+<GenerateConsts :dataName="'MH'" :dataPath="'header'"/>

devices/api/sdks/toit/getting-started.md

@@ -126,7 +126,9 @@ Once the code is running, you should see some output through the `monitor` comma
 💬 Sending text to device
 ```
 
-And you should see the device screen update, saying `Lightbug...` in the top right.
+And you should see the device screen update, saying `Lightbug...` in the top left.
+
+![](https://i.imgur.com/8QP1022.png)
 
 ### 7. Inspect the code