Brain Control Network Protocol (BCNP)

2.1. Terminology

Control Network:

A network comprising one Controller and a set of Devices, in which the Controller configures and commands the Devices.¶

Controller:

A software program that configures and commands a set of Devices via the Probes defined in this document. This document assumes no specific Controller user interface or input mechanism; see Introduction (Section 1) for the brain-computer interface use case that motivates BCNP's design.¶

Device:

A software program that listens for configuration and commands from a Controller.¶

Probe:

A single, discrete unit of Controller input, corresponding to one command a Controller's operator can produce. A Controller has seven Control Probes (Discover, Hello, Register, Forget, End, Collection, Device) and K Key Probes, numbered 0 to K-1.¶

K:

The number of Key Probes available to a Controller. K is fixed for a given Controller and is expected to correspond to however many distinct inputs its underlying input mechanism can reliably distinguish. K bounds the range of Collection Key, Device Key, Action Key, and Temporary Device Key; it does not bound Root Action Key or Sequence ID. Because these bounded fields are each carried in one byte on the wire (see Message Format), K MUST be an integer from 1 to 256 inclusive.¶

Collection:

A group of Devices, identified by a unique Collection Key, known to a Controller.¶

Collection Key:

An unsigned integer in the range 0 to K-1, unique among the Collections known to a Controller, used to identify a Collection.¶

Device Key:

An unsigned integer in the range 0 to K-1, unique among the Devices within a single Collection, used to identify a Device. Two Devices in different Collections may share the same Device Key.¶

Action:

A capability of a Device that a Controller can elicit, for example turning on an LED.¶

Action Key:

An unsigned integer in the range 0 to K-1, unique among the Actions registered for a single Device, used to identify an Action once a Controller has Paired with that Device.¶

Root Action Key:

An unsigned integer in the range 0 to 255, assigned by a Device to identify one of its own Actions. Unlike Action Key, Root Action Key is not bounded by K: a Device's Root Action Keys need not be contiguous, and a Device may have more Actions than a given Controller's K. See Protocol Operation (Section 5) for how a Controller addresses a Device's Actions when they outnumber K.¶

Temporary Device Key:

An unsigned integer in the range 0 to K-1, assigned by a Controller during the Device Configuration Phase to temporarily identify a Device that has not yet been assigned a Device Key.¶

Device Configuration Phase:

Also referred to as "Discovery". The process by which a Controller discovers Devices and assigns each a Collection Key and a Device Key.¶

Action Configuration Phase:

Also referred to as "Pairing". The process by which a Controller, having opened a persistent connection to a single Device, discovers that Device's Actions and assigns each an Action Key.¶

Commanding:

The process by which a Controller elicits a Device to perform an Action, outside of the Device Configuration Phase or Action Configuration Phase.¶

Temporary Device Map:

A construct held in a Controller's volatile memory, mapping each currently assigned Temporary Device Key to the Network ID of the Device holding it, for the duration of a single Device Configuration Phase.¶

Device Map:

A construct held in a Controller's persistent storage, mapping each Device Key, within a Collection, to the last known Network ID of the Device holding it. A Device's Network ID is not assumed to remain stable; see Protocol Operation (Section 5) for the reconciliation mechanism used to recover a Device's current Network ID.¶

Action Map:

A construct, held independently in the persistent storage of both a Controller and a Device, mapping each Action Key to the corresponding Root Action Key.¶

Network ID:

The address of a Device on the Control Network, for example an IP address.¶

Status Code:

A single-byte value, carried in most response messages, indicating the outcome of the request being acknowledged. See Message Format (Section 4).¶

Reconciliation:

The process by which a Controller recovers from an operation that failed or timed out, by querying whether a Device holding a specific Collection Key and Device Key pair can still be located. See Protocol Operation (Section 5).¶

3.1. Deployment Model

BCNP assumes a Controller establishes its own wireless network, and that Devices join that network through some out-of-band mechanism before engaging in BCNP; the specifics of that mechanism are out of scope for this document. This document further assumes a single Controller per Control Network: a Device holds at most one Collection Key and Device Key at a time, and this document does not define behavior for a second Controller attempting to configure a Device already claimed by another. Both of these are scoping decisions rather than protocol requirements as such; see Security Considerations (Section 6) for the trust model this deployment assumption enables.¶

Because Collection Key, Device Key, and Action Key are each bounded to the range 0 to K-1 (see "K" in Section 2.1), a single Controller can, per Collection, address at most K Devices, each with at most K Actions available for direct addressing, for a system-wide ceiling of K x K addressable Devices. This is a deliberate consequence of BCNP's design (see Introduction (Section 1)), not an oversight.¶

4.1. Header

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     Magic     |    Version    | Message Type  |  Sequence ID  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|        Payload Length         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Magic:

Fixed to 0xBC. A receiver MUST discard, without further processing, any message whose Magic byte is not 0xBC.¶

Version:

The protocol version in use. A receiver MUST reject a message carrying a Version it does not support, responding where applicable with Status Code ERR_VERSION.¶

Message Type:

Identifies the message; see "Message Types" below. A receiver MUST discard, without further processing, any message carrying a Message Type this document does not assign.¶

Sequence ID:

Set by the sender of a request. A response MUST echo the same value as the request it answers. BCNP is synchronous: an implementation MUST NOT have more than one request outstanding at a time on a single connection. Under this constraint, wraparound of this one-byte field cannot cause a response to be mismatched to the wrong request.¶

Payload Length:

The number of bytes following the header, encoded in network byte order (big-endian), 0 to 65535.¶

4.2. Notation

The tables below describe each message's payload as an ordered sequence of fields. [field_name:N] denotes a field occupying exactly N bytes at that position; fields are concatenated with no delimiters, since both sides already know the expected shape from the Message Type. + JSON tail denotes that all remaining bytes, up to Payload Length, are one UTF-8 encoded JSON value (see "JSON Schema" below). count x [...] denotes that the bracketed group repeats count times.¶

4.3. Status Codes

Most response messages carry a one-byte Status Code as the first byte of their payload. Codes of local or synthesized origin are never serialized; they are included here to keep the code space in one place, and are cross-referenced from Protocol Operation (Section 5), where the controller behavior that produces them is specified.¶

4.4. Message Types

Message Type is one byte, giving 256 possible values. This document assigns 0x01 through 0x1B; the remainder are unassigned, and, per IANA Considerations (Section 7), this document establishes no registry for allocating them.¶

4.5. JSON Schema

BCNP_ANNOUNCE, BCNP_ANNOUNCE_ACTION, and BCNP_ANNOUNCE_ALL_ACTIONS each carry a JSON tail, encoded in UTF-8 per [RFC8259]. Two distinct shapes are used.¶

5.1. Controller States

A Controller is, at any time, in exactly one of three states.¶

CTRL_STATE_IDLE:

The Controller's resting state. A Controller in this state MAY issue a Command, entering no other state as a result once the exchange completes. A Controller in this state MAY enter CTRL_STATE_DISCOVERING by initiating a Device Configuration Phase, or CTRL_STATE_PAIRED by initiating an Action Configuration Phase.¶

CTRL_STATE_DISCOVERING:

Active for the duration of a Device Configuration Phase (see "Discovery Procedure" below). A Controller in this state MUST NOT issue a Command, and MUST send and accept only Device Configuration Phase messages. A Controller returns to CTRL_STATE_IDLE once the Device Configuration Phase ends.¶

CTRL_STATE_PAIRED:

Active for the duration of an Action Configuration Phase, over the single persistent connection opened by BCNP_PAIR (see "Pairing Procedure" below). A Controller in this state MUST NOT issue a Command, and MUST send and accept only Action Configuration Phase messages on that connection. A Controller returns to CTRL_STATE_IDLE once the persistent connection closes.¶

5.2. Device States

A Device is, at any time, in exactly one of three states, persisted across restarts except where noted.¶

DEV_STATE_UNASSIGNED:

The Device's initial state, and the state a Device returns to after being forgotten. A Device in this state listens for BCNP_DISCOVER and MUST respond with BCNP_ANNOUNCE. A Device in this state MUST evaluate any BCNP_IDENTITY_CHECK it receives (it will never match, holding no Collection Key or Device Key) and MUST silently discard a BCNP_COMMAND. A Device transitions to DEV_STATE_ASSIGNED on receiving a BCNP_REGISTER_DEVICE addressed to its currently held Temporary Device Key.¶

DEV_STATE_ASSIGNED:

A Device holding a Collection Key and Device Key. A Device in this state MUST respond to BCNP_COMMAND (see "Command Procedure" below), MUST respond to BCNP_DISCOVER with a BCNP_ANNOUNCE carrying its current Collection Key and Device Key, and MUST evaluate BCNP_IDENTITY_CHECK, responding with BCNP_IDENTITY_CHECK_ACK if the message includes its own Collection Key and Device Key pair. A Device in this state transitions to DEV_STATE_PAIRED on receiving a BCNP_PAIR that matches its held Collection Key and Device Key, and to DEV_STATE_UNASSIGNED on receiving a matching BCNP_FORGET_DEVICE. A Device's handling of a BCNP_REGISTER_DEVICE that does not exactly match its already-held keys is specified under "Idempotency and Retry Safety" below.¶

DEV_STATE_PAIRED:

A Device with a single persistent connection open to a Controller, entered by way of a successful BCNP_PAIR. A Device in this state MUST NOT act upon any message other than an Action Configuration Phase message received via its open persistent connection; in particular, it MUST NOT act upon a BCNP_COMMAND, regardless of source. A Device in this state MUST close the connection and return to DEV_STATE_ASSIGNED after receiving BCNP_END_PAIR, or after an idle period with no message received from the Controller exceeding a locally configured threshold; the idle period MUST reset on any message received from the Controller, not merely on connection establishment. A Device MUST NOT persist DEV_STATE_PAIRED across a restart: a restarted Device always begins in DEV_STATE_UNASSIGNED or DEV_STATE_ASSIGNED depending on the Collection Key and Device Key recorded in its persistent storage. A Device's handling of a BCNP_PAIR received on the already-open connection is specified under "Idempotency and Retry Safety" below.¶

5.3. Unrecognized Messages

Except where a Controller or Device state's description above specifies otherwise, an implementation MUST silently discard any message that does not apply to its current state.¶

5.4. Local and Synthesized Errors

Six Status Codes are never carried on the wire: a Controller produces each internally, as its own conclusion, without any corresponding message from a Device. Four are explained here; the remaining two, ERR_REGISTER_VERIFY_FAILED and ERR_ACTION_TIMEOUT, are explained where they naturally arise, under "Register Device Verification" and "Command Procedure" respectively.¶

ERR_LOCAL_NOT_FOUND:

Produced when an operation references a Collection Key, Device Key, or Action Key that is not present in the Controller's Device Map or Action Map. Because these maps are authoritative for a Controller operating under the single-Controller assumption in Protocol Overview (Section 3), this check MUST be performed, and MUST fail, before any message is sent; no Device is contacted.¶

ERR_LOCAL_COLLISION:

Produced when a Register operation's target, the new Device Key in BCNP_REGISTER_DEVICE or the new Action Key in BCNP_REGISTER_ACTION, is already occupied in the Controller's Device Map or Action Map. As with ERR_LOCAL_NOT_FOUND, this check MUST be performed locally before any message is sent.¶

ERR_LOCAL_INVALID_STATE:

Produced when a Probe is invoked that does not apply to the Controller's current state (for example, a Register Probe invoked while CTRL_STATE_IDLE; see "Controller States" above). No message is sent.¶

ERR_TIMEOUT:

Produced when a Controller does not receive an expected response to a message it sent, within its configured timeout for that exchange. Unlike the three codes above, this follows an attempt that did reach the network; see "Reconciliation" below for how a Controller acts on it.¶

5.5. Discovery Procedure

A Controller enters CTRL_STATE_DISCOVERING by broadcasting BCNP_DISCOVER to its network, using a broadcast mechanism appropriate to its network layer rather than a connection to each address individually. Every Device in DEV_STATE_UNASSIGNED or DEV_STATE_ASSIGNED that receives this broadcast responds with BCNP_ANNOUNCE, opening its own short-lived connection to do so; a Device in DEV_STATE_PAIRED does not respond. Every message in this phase is sent over its own short-lived connection, opened for that one exchange and closed afterward; a Controller MUST NOT hold a connection open across multiple Discovery-phase exchanges with the same Device.¶

For each responding Device, the Controller assigns a Temporary Device Key by sending BCNP_DISCOVER_ASSIGN, recording the Device's Network ID against that key in its Temporary Device Map on receiving BCNP_DISCOVER_ACK.¶

Once addressed by its Temporary Device Key, a Controller assigns a Device a permanent Collection Key and Device Key by sending BCNP_REGISTER_DEVICE. On receiving BCNP_REGISTER_DEVICE_ACK with Status Code OK, a Controller MUST verify the registration before recording it in its Device Map, using the mechanism described under "Idempotency and Retry Safety" below, rather than committing on the acknowledgment alone.¶

A Controller removes a Device's registration by sending BCNP_FORGET_DEVICE, addressed by that Device's Collection Key and Device Key as currently recorded in its Device Map, removing the corresponding entry on receiving BCNP_FORGET_DEVICE_ACK.¶

A Controller ends a Device Configuration Phase by sending BCNP_END_DISCOVER individually to every Device remaining in its Temporary Device Map. Once every such Device has responded with BCNP_END_DISCOVER_ACK, the Controller discards its Temporary Device Map and returns to CTRL_STATE_IDLE.¶

5.6. Pairing Procedure

A Controller enters CTRL_STATE_PAIRED by sending BCNP_PAIR to a Device already recorded in its Device Map, opening the single persistent connection that remains open for the duration of this phase. BCNP_PAIR carries the Collection Key and Device Key the Controller believes it is addressing; a Device receiving it MUST compare these against its own held Collection Key and Device Key and reject with ERR_IDENTITY_MISMATCH on any mismatch, rather than pairing with whichever Controller happened to reach it.¶

Once paired, a Controller queries a single Action by sending BCNP_DISCOVER_ACTION with the Action's Root Action Key, resolved from the current page if pagination is in use (see "Key Addressing and Pagination" above), receiving its metadata back in BCNP_ANNOUNCE_ACTION. A Controller queries every Action a Device offers at once by sending BCNP_DISCOVER_ALL_ACTIONS, receiving the full set back in a single BCNP_ANNOUNCE_ALL_ACTIONS; this exchange is not subject to pagination, since it addresses no single Action Key.¶

A Controller assigns an Action Key to a Device's Action by sending BCNP_REGISTER_ACTION, and removes an assignment by sending BCNP_FORGET_ACTION, addressed by the already-assigned Action Key. As with BCNP_REGISTER_DEVICE, a Controller MUST verify a BCNP_REGISTER_ACTION_ACK carrying Status Code OK using the mechanism described under "Idempotency and Retry Safety" below before recording it.¶

A Controller ends an Action Configuration Phase by sending BCNP_END_PAIR over the open connection, closing the connection on receiving BCNP_END_PAIR_ACK and returning to CTRL_STATE_IDLE. A Device's own timeout and connection-loss behavior while paired is specified under "Device States" above.¶

5.7. Command Procedure

A Controller in CTRL_STATE_IDLE elicits an Action by sending BCNP_COMMAND, addressed by Collection Key, Device Key, and Action Key, over its own short-lived connection. A Controller MUST NOT issue a further Command, or enter CTRL_STATE_DISCOVERING or CTRL_STATE_PAIRED, until the exchange completes or fails.¶

A Device receiving BCNP_COMMAND responds immediately with BCNP_COMMAND_ACCEPT, before performing the Action, to confirm receipt; Status Code OK indicates the Device will attempt the Action, and any other code indicates outright rejection, in which case no further message follows. Once the Action completes, the Device sends BCNP_COMMAND_ACK carrying the outcome: Status Code OK on success, or ERR_ACTION_FAILED if the Action was attempted and did not succeed. Both messages MUST echo the Sequence ID of the BCNP_COMMAND they answer.¶

A Controller awaits BCNP_COMMAND_ACCEPT for a short, fixed timeout; failing to receive it is handled as specified under "Idempotency and Retry Safety" below. Once BCNP_COMMAND_ACCEPT has been received, a Controller awaits BCNP_COMMAND_ACK for a duration derived from the Action's declared duration (see "JSON Schema" in Message Format) plus a grace period, or for a locally configured default duration if the Action declared none; failing to receive it within that window is a distinct condition, ERR_ACTION_TIMEOUT, also specified under "Idempotency and Retry Safety" below.¶

5.8. Idempotency and Retry Safety

6.1. Trust Model and Scope

BCNP's security properties depend entirely on the deployment model described under "Deployment Model" in Protocol Overview (Section 3): a single Controller establishes its own wireless network, and Devices join that network through an out-of-band mechanism outside the scope of this document. This document treats that network, not any individual BCNP message, as the trust boundary. Every message defined in Message Format (Section 4) is unauthenticated and unencrypted at the BCNP layer; whatever confidentiality and access control exist are provided entirely by the wireless network's own link-layer security (for example, WPA2 or WPA3), not by BCNP itself.¶

This scoping has a direct consequence: BCNP provides no protection whatsoever against a party who is not on the Controller's wireless network. It relies entirely on that network correctly excluding anyone who has not been given credentials to join it. BCNP also provides no protection against a device that is a legitimate, credentialed member of that network but is compromised or malicious; this residual risk is discussed below.¶

BCNP is not designed for, and this document makes no claims about, operation on a network the Controller does not establish and control: for example, a household's existing general-purpose WiFi network shared with other, unrelated devices and users.¶

8.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

8.2. Informative References

[RFC9293]

Eddy, W., Ed., "Transmission Control Protocol (TCP)", STD 7, RFC 9293, DOI 10.17487/RFC9293, August 2022, <https://www.rfc-editor.org/rfc/rfc9293>.