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.