Protocol messaging
←Security and authorization · Index↑ · Data type marshalling→
All protocol messages MUST have the messageType property to indicate the type of the message (e.g. Command).
When sending messages, each message MUST contain a handle numeric identifier. This is then used when responses are received from the device for matching the responses to the messages sent by the controller. The handle has no programmatic significance for the device.
All message results MUST return a response which inherits from the base NcMethodResult that contains a status of type NcMethodStatus. If the method call encountered an error then the response result returned MUST inherit from NcMethodResultError and include an errorMessage of type NcString.
Data types:
| Property | JSON representation |
|---|---|
| messageType | Integer enum value as described below |
| handle | Integer value of the message handle |
enum MessageType {
Command = 0,
CommandResponse = 1,
Notification = 2,
Subscription = 3,
SubscriptionResponse = 4,
Error = 5
}
Control session
The control session context is delegated to the underlying WebSocket transport and its built in mechanisms for detecting communication failure.
When a communication failure occurs, then both the controller and the device MUST dispose of the current WebSocket connection. Controllers can open a new WebSocket connection, but any previous control context is lost and has to be be recreated (e.g. subscriptions have to be reissued and initial states have to be reacquired).
Under normal operating circumstances devices MUST keep the WebSocket connection open until the controller closes the connection.
Concurrency control is left to specific device implementations, however devices MUST always return relevant error messages and statuses when there are conflicts, errors or other noteworthy states (see NcMethodResultError and Error messages).
Command message type
Commands are clearly distinguished using the Command messageType.
Multiple messages MAY be sent in a Command.
Each message MUST have the following:
- handle - numeric message identification used for pairing the response
- oid - unique object id targeted by this message
- methodId - unique method ID specified as the level and index of the method inside the class.
- arguments - dictionary of arguments where the keys are the argument names and the values are their desired values (only needed if the method requires arguments)
Commands MUST be responded to by devices using the CommandResponse messageType and the matching handle for each message.
Command response message type
Command responses are clearly distinguished using the CommandResponse messageType.
Multiple messages MAY be sent in a CommandResponse.
Each message MUST have the following:
- handle - numeric message identification used for pairing the response with the associated command
- result - result returned by the command which inherits from the base NcMethodResult. This means all results MUST have a
statusproperty.
When a method call encounters an error the return MUST be NcMethodResultError or a derived datatype.
Notification message type
Notifications are clearly distinguished using the Notification messageType and are always sent from the device to the controllers subscribed to a particular event.
Multiple messages MAY be sent in a Notification.
Each message MUST have the following:
- oid - unique object id of the emitter
- eventId - unique event Id specified as a level and index.
- eventData - eventData (NcPropertyChangedEventData for property changed events).
Subscription message type
Subscription messages are clearly distinguished using the Subscription messageType.
Each message MUST have the following:
- messageType - describes the message type
- subscriptions - Array of OIDs desired for subscription
Subscription messages MUST be responded to by devices using the SubscriptionResponse messageType.
Subscription response message type
Subscription response messages are clearly distinguished using the SubscriptionResponse messageType.
Each message MUST have the following:
- messageType - describes the message type
- subscriptions - Array of OIDs which have successfully been added to the subscription list
Devices MUST return a response where all the original OIDs requested for subscribing which are valid are in the subscriptions array. Devices are responsible for filtering out invalid OIDs which cannot be subscribed to.
Here is one example.
{
"messageType": 4,
"subscriptions": [
1,
100,
111,
10001
]
}
This allows controllers to know which items they have successfully subscribed to.
Error messages
Error messages are clearly distinguished using the Error messageType.
Each message MUST have the following:
- messageType - describes the message type
- status - status of the message response. Must include the numeric values for NcMethodStatus or other types which inherit from it.
- errorMessage - error details associated with the failure
Error messages MUST be used by devices to return general error messages when more specific responses cannot be returned using the CommandResponse message (for example when incoming messages do not have messageType, handles or contain invalid JSON).
←Security and authorization · Index↑ · Data type marshalling→