Nabto Serial Link Protocol

Transcription

1 Nabto Serial Link Protocol Nabto TM Nabto Serial Link Protocol Page 1 of 22

2 Contents Vocabulary... 4 Introduction... 5 Access Control... 5 Connection type... 5 Access Control List... 5 Protocol details... 6 Binary protocol... 6 Layers... 6 Commands... 8 Status codes... 9 NSLP version request... 9 NSLP version report... 9 Notification Query request Query response Event data push Event data acknowledge Queries Interrogate gateway Get access control list entry Add user to access control list Remove user from access control list Remove all users from access control list Nabto TM Nabto Serial Link Protocol Page 2 of 22

3 Get access control list size Get serial port bitrate Set serial port bitrate Configure network Streams Non-multiplexed stream Gateway settings Maximum packet length Show client id Parallel requests Device id Alternative HTML device driver Unrestricted local connections NSLP IO pins userver IO pins Device implementation check list Maximum packet length Full duplex communication Nabto TM Nabto Serial Link Protocol Page 3 of 22

4 Vocabulary ACL Client Command Device Device Command Device query Gateway Gateway Command Gateway query Local connection NSLP Query Remote connection Access Control List. The method used for permitting and denying specific user actions. 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 Line 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. Nabto TM Nabto Serial Link Protocol Page 4 of 22

5 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 for a detailed description of Nabto. The NSLP protocol is designed to make it possible to expose a device as a Nabto enabled device using a gateway device like the Nabto userver. This setup is illustrated below. Client Device Hostprocessor NSLIP Gateway (Module) Internet Client Device Client Figure 1 A setup using an NSLP gateway. Access Control The NSLP gateway provides two methods of access control namely connection type check and access control list (ACL) check. Furthermore, as the client s id is (optionally) sent to the Device along with Device Requests custom access control can be implemented on the Device. 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 local. In all other cases, the connection type is remote. Local connections automatically pass access control while remote connections must also pass the ACL check described below. Access Control List For a client to pass the ACL check two criteria must be fulfilled: Nabto TM Nabto Serial Link Protocol Page 5 of 22

6 1. The client s id must be present in the ACL. 2. The access rights associated with client s ACL entry must permit the requested action. a. If a client is in the ACL but have no rights the client is considered black listed. The table below lists the rights a user can be assigned including the bit index to use when accessing the actual ACL. Index Name Description 0 Gateway Request Allow the client to send requests to the Gateway. 1 Device Request Allow the client to send requests to the Device. 2 Multiplexed Stream Allow the client to open multiplexed streams. 3 Non- multiplexed Stream Allow the client to open non-multiplexed streams. 4 ACL Allow the client to read and write the ACL. 5 IO Allow control of the IO pins. 6 Configuration Allow changes to be made to the configuration store. 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 information is sent to the Gateway either as a compact binary representation or in human readable format. These representations are referred to as the binary protocol and the textual protocol respectively and are described in detail in the following. Binary protocol The following describes the binary protocol using a layered architecture. Layers NSLP applications NSLP Server NSLP Client Application layer NSA NCA Transport layer Link layer NBT NBT NBL (SLIP) NBL (SLIP) Physical layer UART UART Nabto TM Nabto Serial Link Protocol Page 6 of 22

7 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. 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. Nabto TM Nabto Serial Link Protocol Page 7 of 22

8 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() Commands This section describes the commands provided by the NSLP protocol for communication with the Device. 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 -128 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 Nabto TM Nabto Serial Link Protocol Page 8 of 22

9 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 preceded by a uint16 indicating the number of bytes. string char[] A zero-terminated array of bytes interpreted as an UTF8 string. Status codes Commands and queries share a common set of status values. These are detailed in the table below. Value Name Description 0 Success The requested operation completed successfully. 1 Unable to perform action An error occurred that prevented the requested operation to be completed. 2 Missing rights The user does not have the required access rights to perform the requested operation NSLP version request Requests the version of the NSLP protocol in use on the other NSLP node. Source: Gateway, Device Command identifier: Parameters: None NSLP version report Informs the receiving node of the version of the NSLP in use on the transmitting node. Nabto TM Nabto Serial Link Protocol Page 9 of 22

10 Source: Gateway, Device Command identifier: Parameters: Major version uint32 The major part of the NSLP version number. Minor version uint32 The minor part of the NSLP version number. Notification A notification informs the Device that an event has occurred on the Gateway. Source: Gateway Command identifier: Parameters: The list below enumerates the possible events. Event uint32 The event identifier. See the list below. 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. 6 Event data queue is now empty. 7 Non-multiplexed stream opened. 8 Non-multiplexed stream forced open. Query request Nabto TM Nabto Serial Link Protocol Page 10 of 22

11 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: 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. Query response The packet sent out by a Gateway or a Device as a response to a Query Request command. Source: Gateway, Device Command identifier: Parameters: [Sequence Number] uint32 The sequence number of the query being responded to. This field is only included if Parallel Requests is true. Nabto TM Nabto Serial Link Protocol Page 11 of 22

12 Status uint Unable to perform action 1 - Missing rights to perform action 2 - Parameters uint8[] The query response parameters as specified in the unabto_queries.xml file. 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: Data uint8[] The data to push into the event data queue. 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. Source: Gateway Command identifier: Parameters: Pushed uint16 The number of bytes successfully pushed into the event data queue on the Gateway. Free uint16 The number of bytes currently free in the event data queue on the Gateway. Size uint16 The total size of the event data queue on the Gateway. Nabto TM Nabto Serial Link Protocol Page 12 of 22

13 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. Interrogate gateway Get a list of information objects from the gateway. The HTML device driver may use these objects to adapt to different gateway configurations or revisions. An information object is a key-value pair of the form shown in the table below. Key uint16 The information object identifier Value * The value of the particular information object. The key is a uint32 value from the list below. The value has the data type specified in the list next to identifier. Identifier Value data type Description 0 uint32[] Bootloader version. Index 0 in the array is major version number and index 1 is minor. 1 uint32[] Application version. Index 0 in the array is major version number and index 1 is minor. 2 uint8 ACL enabled. If this key is defined, the gateway uses ACL. The value specifies the number of entries in the ACL. Query identifier: interrogate (0x ) Access rights required: Gateway Request Request format: Response format: LowestIdentifier uint16 The lowest information object identifier to report. Set this field to 0 to include all objects. HighestIdentifier uint16 The highest information object identifier to report. Set this field to to include all objects. Nabto TM Nabto Serial Link Protocol Page 13 of 22

14 Status uint8 See Status Codes above. Data raw The information object array encoded as a byte array. Get access control list entry Get user at the specified entry in the ACL. If an entry outside the range [0..ACL size - 1] is specified an empty entry (name =, rights = 0) will be returned. Query identifier: acl_get_user (0x ) Access rights required: Gateway Request, ACL Request format: Response format: Index uint16 Index in the ACL. Status uint8 0 - Unable to perform action 1 - Missing rights to perform action 2 - Invalid entry specified 3 - Unused entry 4 - Entry in use Name raw The name of the user. Rights uint16 The users access rights. Add user to access control list Add the specified user to the gateway s ACL. If the user is already in the ACL, the user s access rights will be updated. Query identifier: acl_add_user (0x ) Access rights required: Gateway Request, ACL Request format: Nabto TM Nabto Serial Link Protocol Page 14 of 22

15 Name raw The client id. Rights uint16 The access rights to assign to the user. Response format: Status uint8 0 - Unable to perform action 1 - Missing rights to perform action 2 - ACL is full 3 - Nothing changed 4 - User added 5 - Rights updated Remove user from access control list Remove the specified user from the gateway s ACL. Query identifier: acl_remove_user (0x ) Access rights required: Gateway Request, ACL Request format: Response format: Name raw The id of the client to remove. Status uint8 0 - Unable to perform action 1 - Missing rights to perform action 2 - User not found 3 - Success Remove all users from access control list Remove all users from the ACL. This action is irreversible. Query identifier: acl_remove_all (0x ) Access rights required: Gateway Request, ACL Request format: Takes no parameters. Nabto TM Nabto Serial Link Protocol Page 15 of 22

16 Response format: Status uint8 0 - Unable to perform action 1 - Missing rights to perform action 2 - ACL was already cleared 3 - Success Get access control list size Get the size of the ACL. Query identifier: acl_get_size (0x ) Access rights required: Gateway Request, ACL Request format: Takes no parameters. Response format: Status uint8 0 - Unable to perform action 1 - Missing rights to perform action 2 - Success Size uint16 The number of entries the ACL can hold. Get serial port bitrate Returns the serial ports current bitrate. Query identifier: 0x Access rights required: Gateway Request Request format: Store bool If false the value currently in use is returned otherwise the value from the configuration store is returned. Response format: Nabto TM Nabto Serial Link Protocol Page 16 of 22

17 Status uint8 0 - Unable to perform action 1 - Missing rights to perform action 2 - Success Bitrate uint32 The serial ports bitrate. Set serial port bitrate Changes the bitrate of the serial port. Query identifier: 0x Access rights required: Gateway Request Request format: Bitrate uint32 The new bitrate. Store bool If true the new value is persisted and will be reused at reset. Response format: Status uint8 0 - Unable to perform action 1 - Missing rights to perform action 2 - Success Configure network Configures the network interface of the gateway. Query identifier: 0x800000xx Access rights required: Gateway Request, Configuration Request format: IP uint32 IP address of the gateway. Set to 0 to enable DHCP (default). Nabto TM Nabto Serial Link Protocol Page 17 of 22

18 Netmask uint32 Netmask of the gateway. Gateway uint32 The default gateway on the network. DNS uint32 Address of DNS server. Response format: Status uint8 See Status Codes above. Streams A client can open streams to the Device through the Gateway. A stream provides a bidirectional channel between a client and a server appropriate for sending data that is naturally stream oriented (as opposed to the requestresponse 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> [<arguments>]\n The service responds with a Service Response String (SRS). The format of an SRS depends on the service in question but will always be a new-line terminated string. The NSLP server supports the services described below. Non-multiplexed stream A non-multiplexed stream provides a direct client connection to the Gateway s serial port. Every byte written to the stream will appear unaltered at the other end. No encoding or interpretation is performed on this data by the Gateway. The service identifier for non-multiplexed streams is nm nmsp fnmsp msp Once a non-multiplexed stream has been opened, no other streams may be opened. The Gateway also rejects Device Requests. This will continue until the client closes the stream. A non-multiplexed stream cannot be opened when either One or more requests are being executed, or Nabto TM Nabto Serial Link Protocol Page 18 of 22

19 One or more streams are opened When a non-multiplexed stream is requested in one of these circumstances, the stream is closed by the Gateway. Sending a N (upper case N ) instead of a n will force the non-multiplexed stream open and abort all other actions. When a non-multiplexed stream is opened, a notification is sent to the device as the last command before switching to non-multiplexed stream mode on the serial port. A client must have assigned non-multiplexed stream access right to open a non-multiplexed stream. Gateway settings This section details the settings that can be configured on the Gateway. Each parameter is identified by a uint32. The type of the value depends on the parameter. Maximum packet length Identifier: 2 Type: uint16 Value: Default: 100 Show client id Identifier: 4 Type: bool Value: false true Default: false Parallel requests Identifier: 5 Type: bool Value: false true Default: false Device id Identifier: 6 Nabto TM Nabto Serial Link Protocol Page 19 of 22

20 Type: string Value: Default: Note: Changing the gateway s id triggers a reattach of the gateway. Alternative HTML device driver Identifier: 7 Type: string Value: Default: Note: Changing the HTML device driver triggers a reattach of the gateway. Unrestricted local connections If Unrestricted local connections configuration is true local connections bypass the ACL. Identifier: 8 Type: bool Value: Default: true NSLP IO pins The NSLP protocol allows for read and write operations on both digital and analog IO pins. In the NSLP domain, these IO pins are referenced using a zero-based integer identifier. The capabilities of these pins depend on the physical platform. The following table lists the possible capabilities. Capability DO DI AI PWM CNT Description Digital output. Digital input. Analog input. Pulse width modulation output. Counter input. Nabto TM Nabto Serial Link Protocol Page 20 of 22

21 SPI IIC UART SPI serial port. A pin is either SCK, SDI or SDO. IIC serial port. A pin is either SDA or SCL. UART serial port. A pin is either RX or TX. userver IO pins This section describes the capabilities of the IO pins of the userver platform. Identifier Capabilities 0 DI, DO, SPI (SCK), IIC (SCL) 1 DI, DO, SPI (SDI), IIC (SDA) 2 DI, DO, SPI (SDO) 3 DI, DO 4 DI, DO 5 DI, DO, UART (RX) 6 DI, DO, UART (TX) 7 DI, DO, CNT 8 DI, DO, PWM 9 DI, DO, AI 10 DI, DO, AI Device implementation check list 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. Maximum packet length The receiving state machine must be able to handle the specified packet length (not including framing and byte stuffing). Full duplex communication Nabto TM Nabto Serial Link Protocol Page 21 of 22

22 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 TM Nabto Serial Link Protocol Page 22 of 22