Nabto SDK Nabto Serial Link Protocol

Transcription

1 Nabto SDK Nabto Serial Link Protocol Nabto/001/TEN/011 Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 1 of 23

2 Vocabulary Contents 1 Vocabulary Introduction Access control Connection type Access control check Protocol details Binary protocol Layers Commands NSLP version request NSLP version report Notification Query request Query response Event data push Event data acknowledge Stream request Stream response Stream data Queries Get gateway information Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 2 of 23

3 Vocabulary 6.2 Access control Get users from access control list Add user to access control list Remove user from access control list Get allow remote access Set allow remote access Get default local permissions Set default local permissions Get default remote permissions Set default remote permissions Gateway configuration Get communications port bitrate Set communications port bitrate Get alternative device id Set alternative device id Get alternative HTML device driver Set alternative HTML device driver IO pin control Get pin mode Set pin mode Get digital pin value Set digital pin value Streams Multiplexed stream Non- multiplexed stream Forced non- multiplexed stream Check list for device application creators Maximum packet length Full duplex communication Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 3 of 23

4 Vocabulary 1 Vocabulary ACL Access Control List. The method used for permitting and denying specific user actions. Client Command Device Device Command Device query Gateway Gateway Command Gateway query Local connection NSLP Query Remote connection Communications port A Nabto client. Either a Nabto enabled browser or an application using the client API. Used for communication between Gateway and Device. A unit using the Gateway to communicate with Nabto clients. A command sent from the Gateway to the Device. A query forwarded by the Gateway and handled by the Device. Device queries have a query identifier in the range [0x x7FFFFFFF]. A unit implementing the NSLP protocol to function as a gateway between Nabto clients and a Device. A command sent from the Device to the Gateway. A query handled by the Gateway. Gateway queries has a value query identifier in the range [0x xFFFFFFFF]. A connection to the Gateway from a client located on the same physical network as the Gateway. Nabto Serial Link Protocol. Used for communication between Gateway and Client. A connection to the Gateway from a client not located on the same physical network as the Gateway. The port through which the gateway communicates with the device (i.e. the serial port). Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 4 of 23

5 Introduction 2 Introduction This document is the specification of the Nabto Serial Link Protocol (NSLP). Previous knowledge of Nabto is required to read this specification. Please refer to Nabto s starter kit documentation on nabto.com/technology for a detailed description of Nabto. The NSLP protocol is designed to expose a device as a Nabto enabled device using a gateway device like the Nabto userver. This setup is illustrated below. Figure 1 A setup using an NSLP gateway. 3 Access control The NSLP gateway provides access control based on the client s id ( ) and connection type. Furthermore, as the client s id is (optionally) sent to the Device along with forwarded requests fine- grained custom access control can be implemented on the Device. 3.1 Connection type The Gateway distinguishes between clients connected to the same physical network as the Gateway and those that are not. When a client is located on the same physical network, the connection type is denoted local. In all other cases, the connection type is remote. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 5 of 23

6 Protocol details 3.2 Access control check For a query or stream request from a client to pass the access control one of the following checks must pass: 1. The user must be locally connected, be present in the ACL and have assigned both LOCAL_ACCESS permission and whatever permissions are required by the request. 2. The user must be remotely connected, be present in the ACL and have assigned both REMOTE_ACCESS permission and whatever permissions are required by the request. Remote access must be enabled. 3. The user must be locally connected and the default local user is assigned both LOCAL_ACCESS permission and whatever permissions are required by the request. 4. The user must be remotely connected and the default remote user is assigned both REMOTE_ACCESS permission and whatever permissions are required by the request. Remote access must be enabled. The table below lists the permissions a user can be assigned. Index Name Description 0 Local access Permit local connection establishment. 1 Remote access Permit remote connection establishment. 2 Gateway request Permit execution of requests on the gateway. 3 Device request Permit execution of requests on the device. 4 Multiplexed stream Permit creation of a multiplexed stream. 5 Non- multiplexed stream Permit creation of a non- multiplexed stream. 6 Forced non- multiplexed stream Permit creation of a forced non- multiplexed stream. 7 Access control Permit interaction with the access control settings. 8 IO control Permit control of the IO pins. 9 Configuration Permit interaction with the gateway configuration. 4 Protocol details The Device communicates with the Gateway using commands. A command consists of a command identifier and, if appropriate, one or more parameters. This section describes this protocol in details. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 6 of 23

7 Protocol details 4.1 Binary protocol The following describes the binary protocol using a layered architecture Layers NSLP applications NSLP Server NSLP Client Application layer NSLP Server API NSLP Client API Transport layer NSLP Binary Transport NSLP Binary Transport Link layer NSLP Binary Link NSLP Binary Link Physical layer Communications port Communications port NSLP applications NSLP Server Implemented by Nabto NSLP Client Implemented by the customer to interface with a NSLP gateway. Builds on top of the NSLP client API. A demonstration implementation is provided by Nabto Application layer Exposes the NSLP command API to applications Responsibilities Construction of outgoing packets and decoding of incoming packets. Converts from NSLP endianness to host endianness (where necessary) NSLP Server API Exposes the commands relevant for a server application NSLP Client API Exposes the commands relevant for a client application Transport layer (NSLP Binary Transport - NBT) Provides reliable transfer of packets between two NSLP nodes Responsibilities Transmission and reception of packets. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 7 of 23

8 Commands Checksum generation and check to detect damaged packets. Sequence number generation and check to avoid duplicated packets Interface Send Receive The checksum is the ones - complement sum of all header and payload bytes. During checksum calculation, the checksum field in the header must be zero Link layer (NSLP Binary Link - NBL) Responsibilities Transmission and reception of frames. Framing. Byte stuffing Interface void Send(uint8* frame, uint16 framelength) uint16 Receive(uint8* frame) The standard link layer protocol for NSLP is SLIP. Please refer to RFC1055 for details on SLIP Physical layer The actual physical layer depends on the physical platform used. The general term communication port is used which will in most applications be a UART Interface void Write(uint8) uint8 Read() uint16 CanWrite() uint16 CanRead() 5 Commands This section describes the commands provided by the NSLP protocol for communication with the Device. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 8 of 23

9 Commands Commands can originate from either the Gateway or the Device. Both the Gateway and the Device send commands in a stop- and- wait manner in which the other end must acknowledge a packet (if appropriate) before the next packet can be sent. As a result, both ends must be able to accept a command while waiting for an acknowledge packet. The table below lists the data types used in commands. NSLP operates in big endian mode. Name C equivalent Description uint8 uint8_t A single byte interpreted as an unsigned number in the range 0 through 255. int8 int8_t A single byte interpreted as a signed number in the range through 127. uint16 uint16_t Two bytes interpreted as an unsigned number in the range 0 through int16 int16_t Two bytes interpreted as a signed number in the range through uint32 uint32_t Four bytes interpreted as an unsigned number in the range 0 through int32 int32_t Four bytes interpreted as a signed number in the range through uint8[] uint8_t[] A sequence of bytes proceeded by a uint16 indicating the number of bytes. string uint8[] An array of bytes as above with a terminating zero at the end to make it a correct C style string. Encoding is UTF NSLP version request Requests the version of the NSLP protocol in use on the other NSLP node. Source: Gateway, Device Command identifier: Parameters: None Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 9 of 23

10 Commands 5.2 NSLP version report Informs the receiving node of the version of the NSLP in use on the transmitting node. Source: Gateway, Device Command identifier: Parameters: Field Data type Description Major version uint32 The major part of the NSLP version number. Minor version uint32 The minor part of the NSLP version number. 5.3 Notification A notification informs the Device that an event has occurred on the Gateway. Source: Gateway Command identifier: Parameters: Field Data type Description Event uint32 The event identifier. See the list below. The list below enumerates the possible events. Identifier Event 1 Ethernet link state changed from down to up. 2 Ethernet link state changed from up to down. 3 DHCP assignment succeeded. 4 Connection to GSP established. 5 Connection to GSP lost. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 10 of 23

11 Commands 6 Event data queue is now empty. 7 Non- multiplexed stream opened. 5.4 Query request The Query Request command is sent to the Device, when the Gateway receives a Device Query i.e. a query not intended for the Gateway itself. A device may also use this command to execute queries on the Gateway. Source: Gateway, Device Command identifier: Parameters: Field Data type Description Flags uint32 Bit 0: fromlocalnetwork. This bit is set if the request originated from the LAN. Bit 1: fromserialport: This bit is set if the request originated from the serial port. All other bits are reserved for future use and should be ignored. [Sequence Number] uint32 A unique sequence number identifying this specific query. This must be used when acknowledging or responding to the query. This field is only included if the configuration flag Parallel Requests is true. [Client id] string The id of the client sending the request. This field is only included if configuration flag Show client id is true. Identifier uint32 The query identifier as specified in the unabto_queries.xml file. Parameters uint8[] The query request parameters as specified in the unabto_queries.xml file. 5.5 Query response The packet sent out by a Gateway or a Device as a response to a Query Request command. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 11 of 23

12 Commands Source: Gateway, Device Command identifier: Parameters: Field Data type Description [Sequence Number] uint32 The sequence number of the query being responded to. This field is only included if Parallel Requests is true. Status uint32 See section Error! Reference source not found.. Parameters uint8[] The query response parameters as specified in the unabto_queries.xml file. 5.6 Event data push Push data into the Gateways event data queue. For more information about the Event Data channel, please refer to document <TEN004 Nabto Piggyback Message system.docx> Hint: To determine the size of the event data queue on the Gateway send an Event Data Push command with no data. Source: Device Command identifier: Parameters: Field Data type Description Data uint8[] The data to push into the event data queue. 5.7 Event data acknowledge Acknowledge a previous push command informing the Device of the amount of data that was successfully pushed and the amount of free space in the data queue. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 12 of 23

13 Commands Source: Gateway Command identifier: Parameters: Field Data type Description Pushed uint32 The number of bytes successfully pushed into the event data queue on the Gateway. Free uint32 The number of bytes currently free in the event data queue on the Gateway. Size uint32 The total size of the event data queue on the Gateway. 5.8 Stream request A client requests that a stream be opened. Source: Gateway Command identifier: Parameters: Field Data type Description Type uint8 0: multiplexed, 1: non- multiplexed Identifier uint8 The identifier of the stream. Used when performing subsequent stream operations. Only relevant for multiplexed streams. Always 0 when not used. 5.9 Stream response Used by the device to either accept or reject a stream request. Source: Device Command identifier: Parameters: Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 13 of 23

14 Queries Field Data type Description Identifier uint8 The identifier of the stream. Used when performing subsequent stream operations. Only relevant for multiplexed streams. Always 0 when not used. Accepted uint8 0: stream rejected, 1: stream accepted 5.10 Stream data Pushes data through a multiplexed stream. Source: Device, Gateway Command identifier: Parameters: Field Data type Description Identifier uint8 Stream identifier. Data uint8[] The data being pushed through the stream. 6 Queries This section describes the Nabto queries accepted by the Gateway. These queries are termed Gateway Queries, as they are targeting the gateway itself. Each query is described along with its input and output parameters, its query id and the access rights required to execute it. 6.1 Get gateway information Get a list of information key- value pairs from the gateway. The HTML device driver may use these key- value pairs to adapt to different gateway configurations and revisions. A key- value pair is a text string of the form key=value Possible Information keys are listed in the table below. Key Description Example Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 14 of 23

15 Queries hardware_version Hardware version of the gateway. hardware_version=1.1 software_version Version of the gateway application. application_version= acl_size Number of entries in the ACL. acl_size=10 Query: get_gateway_information.json Permissions required: Gateway request Request parameters: Response parameters: 6.2 Access control This group of queries enables configuration of the access control system of the gateway Get users from access control list Get a list of users from the ACL starting at the specified index. Zero or more users will be returned. Multiple queries may be needed to get the full ACL depending on the length of the ACL and the gateway device. Query: access_control_get_users.json Permissions required: Gateway request, Access control Request format: uint16 startingindex. Index of the first user to retrieve. uint16 maximumnumberofusers. Maximum number of users to retrieve in this query. Response format: List: o o raw . The user s address. uint32 permissions. The access permissions granted to this user. uint16 totalnumberofusers. The total number of users in the ACL. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 15 of 23

16 Queries Add user to access control list Add the specified user to the ACL. If the user is already in the ACL, the access permissions will be updated. Query: access_control_add_user.json Permissions required: Gateway request, Access control Request format: raw . The user s address. uint32 permissions. The access permissions granted to this user. Response format: (none) Remove user from access control list Remove the specified user from the ACL. Query: access_contron_remove_user.json Permissions required: Gateway request, Access control Request format: raw . The user s address. Response format: (none) Get allow remote access Get the current state of the allow_remote_access access control flag. Remote access to the gateway and device is only possibly if this flag is set to 1. Query: access_control_get_allow_remote_access.json Permissions required: Gateway request, Access control Request parameters: (none) Response parameters: uint8 value. The current value of the allow_remote_access flag Set allow remote access Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 16 of 23

17 Queries Set the state of the allow_remote_access access control flag. Query: access_control_set_allow_remote_access.json Permissions required: Gateway request, Access control Request parameters: uint8 value. Set to 1 to allow remote access or 0 to disallow remote access. Response parameters: (none) Get default local permissions Get the permissions assigned to local users not in the ACL. Query: access_control_get_default_local_permissions.json Permissions required: Gateway request, Access control Request parameters: (none) Response parameters: uint32 value. The permissions bit mask. See section Access Control for more info Set default local permissions Set the permissions assigned to local users not in the ACL. Query: access_control_set_default_local_permissions.json Permissions required: Gateway request, Access control Request parameters: uint32 value. The permissions bit mask. See section Access Control for more info. Response parameters: (none) Get default remote permissions Get the permissions assigned to remote users not in the ACL. Query: access_control_get_default_local_permissions.json Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 17 of 23

18 Queries Permissions required: Gateway request, Access control Request parameters: (none) Response parameters: uint32 value. The permissions bit mask. See section Access Control for more info Set default remote permissions Set the permissions assigned to remote users not in the ACL. Query: access_control_set_default_local_permissions.json Permissions required: Gateway request, Access control Request parameters: uint32 value. The permissions bit mask. See section Access Control for more info. Response parameters: (none) 6.3 Gateway configuration Get communications port bitrate Get the bitrate currently in use on the communications port. Query: configuration_get_communications_port_bitrate.json Permissions required: Gateway request, Configuration Request parameters: (none) Response parameters: uint32 value. The actual bitrate in bits per second Set communications port bitrate Set the desired bitrate for the communications port. If the specified bitrate is not supported by the device nothing will be changed. The supported values depends on the actual gateway device. Query: configuration_set_communications_port_bitrate.json Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 18 of 23

19 Queries Permissions required: Gateway request, Configuration Request parameters: uint32 value. The desired bitrate in bits per second. Response parameters: (none) Get alternative device id Get the currently assigned alternative device id. Query: configuration_get_alternative_device_id.json Permissions required: Gateway request, Configuration Request parameters: (none) Response parameters: raw value. The current alternative device id Set alternative device id Assign an alternative device id to the device. If a zero- length string is specified the device s default device id will be used. Query: configuration_set_alternative_device_id.json Permissions required: Gateway request, Configuration Request parameters: raw value. The alternative device id to use. Request parameters: (none) Get alternative HTML device driver Get the currently assigned alternative HTML device driver. Query: configuration_get_alternative_html_device_driver.json Permissions required: Gateway request, Configuration Request parameters: (none) Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 19 of 23

20 Queries Response parameters: raw value. The current alternative HTML device driver Set alternative HTML device driver Assign an alternative HTML device driver to the device. If a zero- length string is specified the device s default HTML device driver will be used. Query: configuration_set_alternative_html_device_driver.json Permissions required: Gateway request, Configuration Request parameters: raw value. The alternative HTML device driver to use. Request parameters: (none) 6.4 IO pin control This group of queries allows for client interaction with the physical IO pins of the gateway device. Please refer to the datasheet for the actual gateway device to see which pins are available. IO pins can be configured for one of the following modes: Digital input (power- on default) Digital output Get pin mode Get the current mode of the IO pin. Query: io_get_pin_mode.json Permissions required: Gateway request, IO Request parameters: uint8 pin. Index of the pin. Response parameters: uint8 mode. The current mode of the pin. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 20 of 23

21 Queries Set pin mode Set the mode of the IO pin. Query: io_set_pin_mode.json Permissions required: Gateway request, IO Request parameters: uint8 pin. Index of the pin. uint8 value. The new mode of the pin. Response parameters: (none) Get digital pin value Get the current value of the pin. Only used for pins configured for digital input or digital output. Query: io_get_digital_pin_value.json Permissions required: Gateway request, IO Request parameters: uint8 pin. Index of the pin. Response parameters: uint8 value. The current value of the pin Set digital pin value Set the value written to the pin. Only used for pins configured for digital output. Query: io_set_digital_pin_value.json Permissions required: Gateway request, IO Request parameters: uint8 pin. Index of the pin. uint8 value. The new value of the pin. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 21 of 23

22 Streams Response parameters: (none) 7 Streams A client can open streams to the Device through the Gateway. A stream provides a bidirectional channel between a client and the device appropriate for sending data that is naturally stream oriented (as opposed to the request- response based Device queries). Once a stream has been opened to the gateway, a Service Configuration String (SCS) must be sent. A SCS has the following format: service_identifier [parameters]\n The service responds with a Service Response String (SRS) of the following format: + - [parameters]\n A response starting with a + indicates success. The NSLP server supports the services described below. 7.1 Multiplexed stream Service identifier: muxstream Required rights: Multiplexed stream Multiplexed streams allow multiple clients to establish streams to the application running on the Device. On the device each stream is identified by an integer allowing the 7.2 Non- multiplexed stream Service identifier: nonmuxstream Required rights: Non- multiplexed stream A non- multiplexed stream provides a client with direct access to the Gateway s communications port. Every byte written to the stream will appear unaltered at the communications port and vice versa. The gateway will perform no framing or encoding on the data. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 22 of 23

23 Check list for device application creators When a non- multiplexed stream is requested, no new commands or Device Requests will be accepted. Any pending commands or requests will be completed and a non_multiplexed_stream_opened notification will be sent to the Device. When the notification has been sent, the stream is opened. Once opened, no other streams (of any kind) may be opened. The Gateway also rejects Device Requests. This will continue until the client closes the stream or until the connection to the client is lost. 7.3 Forced non- multiplexed stream Service identifier: forcednonmuxstream Required rights: Forced non- multiplexed stream The forced non- multiplexed stream operates as the non- multiplexed stream described above except it does not wait for commands and requests to complete and it does not send a notification to the Device. Instead, it immediately switches to non- multiplexed stream mode. 8 Check list for device application creators The intention of the section is to give the designer of NSLP protocol clients (devices) a list of things to keep in mind when integrating an NSLP server in a design. 8.1 Maximum packet length The receiving state machine must be able to handle the specified packet length (not including framing and byte stuffing). 8.2 Full duplex communication The NSLP protocol handler on the Device must be able to handle an incoming packet while it itself is sending a packet or waiting for a packet acknowledgement. Nabto Nabto/001/TEN/011 Nabto Serial Link Protocol Page 23 of 23