Request Frames
Each Blecon request is broken down into frames (outgoing and incoming).
Protocol Overview
A new request is created by sending an Open Frame. Each endpoint can then send one Header Frame (differs on the outgoing and incoming directions) and one or more Data Frames.
Once an endpoint has no more data to send, it sends a Data Frame with its finished bit set. After that, the request is considered half-closed and the enpoint must not send further data frames. The request is considered fully closed when both endpoints have half-closed the request.
Additionally, at any point, either endpoint can send a Reset Frame to signal immediate termination of a request.
When flow control is enabled in an Open Frame, the device also sends Credit Frames to manage incoming flow control. The service will consume one available credit per Data Frame it sends back.
Each request is assigned a request ID which must be unique within a connection.
Frames
All data is encoded as little endian.
Frame Header
Each frame contain a three byte header.
Field | Size (bytes) | Description |
---|---|---|
Request ID | 2 | A unique identifier for the request |
Type | 1 | The frame type (see below) |
Open Frame
Frame Type: 0
Field | Size (bytes) | Description |
---|---|---|
Flow-Control enabled | 1 | 1 to enable flow control, 0 otherwise |
Initial Credits | 2 | If flow control is enabled, the number of initial credits to give the service |
MTU | 2 | The maximum size of data the device can receive in each data frame |
Outgoing Header Frame
Frame Type: 1
Field | Size (bytes) | Description |
---|---|---|
Header Bitmask | 4 | Bit 0: One-way request Bit 1: Namespace header present Bit 2: Method header present Bit 3: Request content type present Bit 4: Response content type present |
This is followed by a series of length-prefixed strings for each of namespace, method, request and response content types when present:
Field | Size (bytes) | Description |
---|---|---|
String Size | 2 | The size of the following string |
String | String Size | An UTF-8, non-zero terminated string |
Incoming Header Frame
Frame Type: 2
Field | Size (bytes) | Description |
---|---|---|
Status Code | 2 | A code signalling whether the request was successful |
List of status codes:
Error Code | Description |
---|---|
0x0 | OK |
0x100 | Timeout |
0x101 | Security Error |
0x102 | Disconnection Error |
0x200 | Handler not set |
0x201 | Handler Timeout |
0x202 | Handler Failed |
0x203 | Network not set |
Data Frame
Frame Type: 3
Field | Size (bytes) | Description |
---|---|---|
Finished Byte | 1 | 1 if finished (the request becomes half-closed), 0 otherwise |
Credit Frame
Frame Type: 4
Field | Size (bytes) | Description |
---|---|---|
Credits | 2 | The number of additional credits to give the service |
Reset Frame
Frame Type: 5
This frame has no payload.
Last updated