NOKIA M2M SYSTEM PROTOCOL 2 SPECIFICATION. Copyright 2004 Nokia. All rights reserved. Issue

Transcription

1 NOKIA M2M SYSTEM PROTOCOL 2 SPECIFICATION Copyright 2004 Nokia. All rights reserved. Issue

2 Contents ACRONYMS AND TERMS...1 DEFINITIONS AND SYMBOLS ABOUT THIS DOCUMENT INTRODUCTION PHYSICAL INTERFACE OVERVIEW PHYSICAL CONNECTION HANDSHAKING ASYNCHRONOUS TRANSMISSION TRANSMISSION SPEED DATA LINK LAYER OVERVIEW REQUIREMENTS FOR THE PHYSICAL LAYER DATA LINK PROTOCOL ELEMENTS Terminology Packet format Transparency Error check Elements of a data link layer procedure Link request format Link acknowledgement format Link transfer packet Variables and sequence numbers DATA LINK PROTOCOL DESCRIPTION Link establishment phase procedure Sending LR packets Receiving LR packets Receiving LA packets Data transfer phase procedure Sending LT packets...16

3 Receiving LT packets Sending LA packets Receiving LA packets Retransmission of LT packets Link failure detection Receiving LR packets DATA LINK SYSTEM PARAMETERS Time control T Time control T Time control T Time control T The maximum length parameter N The maximum number of retransmissions N The maximum number of activity timeouts N NETWORK LINK LAYER OVERVIEW NETWORK LINK LAYER PACKET FORMAT Data types Packet header Extension field Extension elements Network Link Layer packet examples PROTOCOL PRIMITIVES RESET AND STARTUP RESET RESET_RESP Both ends resetting simultaneously LINK CONTROL LINK LINK_RESP LINK_OPEN LINK_OPEN_RESP LINK_STATUS_NOTIFICATION LINK_STATUS_ NOTIFICATION_RESP...33

4 5.5.7 LINK_CLOSE LINK_CLOSE_RESP SOCKET CONTROL OPERATIONS Local addressing SOCKET SOCKET_RESP SOCKET_CLOSE SOCKET_CLOSE_RESP BIND BIND_RESP LISTEN LISTEN_RESP ACCEPT_NOTIFICATION ACCEPT_NOTIFICATION_RESP CONNECT CONNECT_RESP SEND SEND_RESP SENDTO SENDTO_RESP SCKT_FLOW_CTRL_NOTIFICATION SCKT_FLOW_CTRL_NOTIFICATION_RESP RECEIVE RECEIVE_RESP RECEIVE_NOTIFICATION RECEIVE_NOTIFICATION_RESP GETHOSTBYNAME GETHOSTBYNAME_RESP SPECIAL OPERATIONS GET_IDENTITY GET_IDENTITY_RESP EXTENDED OPERATIONS CONNECT_EXT CONNECT_EXT_RESP...55

5 APPENDIX A: OPERATION CODES...56 APPENDIX B: PROTOCOL CONSTANTS...57 APPENDIX C: M2M SYSTEM PROTOCOL 2 CHARACTERISTICS FOR THE NOKIA 12 GSM MODULE...61 APPENDIX D: MINIMUM IMPLEMENTATION REQUIREMENTS FOR THE M2M SYSTEM PROTOCOL APPENDIX E: AN EXAMPLE OF PARALLEL FCS CALCULATION...64 APPENDIX F: SDL REPRESENTATION OF THE DATA LINK LAYER...70

6 Legal Notice Copyright 2004 Nokia. All rights reserved. Reproduction, transfer, distribution or storage of part or all of the contents in this document in any form without the prior written permission of Nokia is prohibited. Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners. Nokia operates a policy of continuous development. Nokia reserves the right to make changes and improvements to any of the products described in this document without prior notice. Under no circumstances shall Nokia be responsible for any loss of data or income or any special, incidental, consequential or indirect damages howsoever caused. The contents of this document are provided "as is". Except as required by applicable law, no warranties of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose, are made in relation to the accuracy, reliability or contents of this document. Nokia reserves the right to revise this document or withdraw it at any time without prior notice.

7 ACRONYMS AND TERMS Acronym/term AM API ASCII BSD CORBA CRC CTS DLE DLL DNS DTE FCS HLA LA LR LT M2M MRU MTU NLL ORB PSN RTS SDL TCP UDP Description Application Module Application Programming Interface American Standard Code for Information Interchange Berkeley Standard Distribution Common Object Request Broker Architecture Cyclic Redundancy Check Clear-to-Send Data Link Escape Data Link Layer Domain Name Server Data Terminal Equipment Frame Check Sequence Home Location Agent Link Acknowledgement Link Request Link Transmit Machine-to machine Maximum Receive Unit Maximum Transfer Unit Network Link Layer Object Request Broker Packet Sequence Number Request-to-Send Specification and Description Language Transmission Control Protocol User Datagram Protocol 1/87

8 DEFINITIONS AND SYMBOLS Definitions Character: Control message: Data message: DLE stuffing: Header: Message: Packet body: Start bit: Stop bit: Start flag: Stop flag: Eight bits (an octet) of data combined with Start and Stop bits. A message intended for layer control. A message intended for the transmission of higher layer data (user data). A method to ensure transparent data transmission and reliable packet start and end indication. The layer control part of a message. A generic name for control and data messages. The section of the data link control and higher layer information between start and stop sequences. The bit that identifies the beginning of an asynchronous character. The bit that identifies the end of an asynchronous character. A unique data link packet start sequence used for receiver synchronisation. A unique data link packet end sequence used for receiver synchronisation Symbols C1: The retransmission counter. AR: Parameter for immediate acknowledgement request. k: The maximum number of unacknowledged sequentially numbered user data packets at a specific time. N1: The maximum information length of an LT packet. N2: The maximum number of packet retransmissions. N3: The number of activity timeouts before link failure is detected. T0: The retry waiting time in the establishment phase after which a retransmission of a packet is initiated. T1: The retry waiting time in the data transfer phase after which a retransmission of a packet is initiated. T2: The waiting time after which a transmission of an acknowledgement is initiated. T3: The inactivity time after which a transmission of an acknowledgement to report the receiving state is initiated. T4: Link failure detection time. 2/87

9 VERSION Protocol version number. 3/87

10 1 ABOUT THIS DOCUMENT This document specifies the M2M System Protocol 2. It describes the physical interface, Data Link Layer (DLL) and Network Link Layer (NLL) of the M2M System Protocol 2. It also provides additional information on the operation codes, protocol constants, Frame Check Sequence (FCS) calculation, and Specification and Description Language (SDL) representation related to the M2M System Protocol 2. Note: This specification provides a generic description of the M2M System Protocol 2 functionality between the Application Module (AM) and the Nokia M2M module. For more information on the Nokia 12 GSM module -specific characteristics, see Appendix C: M2M System Protocol 2 characteristics for the Nokia 12 GSM module. 4/87

11 2 INTRODUCTION The M2M System Protocol 2 enables IP based traffic (UDP datagrams, TCP sockets, and link control) between the AM and the Nokia M2M module. From the IP addressing point of view the M2M System Protocol 2 functions as a tunnel that combines the AM and the Nokia M2M module. Because the AM and the Nokia M2M module share the same IP address and TCP/UDP stack (located in the Nokia M2M module), all external components view them as one entity. The M2M System Protocol 2 is used to integrate the AM with the Nokia M2M module. For more information on the integration process, see the Nokia M2M System Protocol 2 Socket Interface User Manual. 5/87

12 3 PHYSICAL INTERFACE 3.1 OVERVIEW The physical interface describes the physical data connections between the AM used as Data Terminal Equipment (DTE) and the Nokia M2M module. This definition covers a point-to-point type connection using a serial mode transmission. It defines the lowest layer transmission format. 3.2 PHYSICAL CONNECTION In this specification the Nokia M2M module represents the Data Communications Equipment (DCE), which is fitted with an M2M System Connector. 3.3 HANDSHAKING Request-to-Send (RTS)/ Clear-to-Send (CTS) handshaking signals are required to allow devices connected to the M2M System Connector to communicate with the Nokia M2M module. The RTS/CTS handshaking method is a widely used flow control method. With the M2M System Protocol 2 the signals are used to disable/enable communication between devices, not to control the data flow between the AM and the Nokia M2M module. Before the AM can send a packet to the Nokia M2M module, it must first reserve a line by setting the RTS line in the M2M System Connector to low state. The AM can start sending data after the Nokia M2M module has released the line by setting the CTS line in the M2M System Connector to the low state. The line is reserved for the AM for as long as the CTS line in the M2M System Connector is held in the low state. 3.4 ASYNCHRONOUS TRANSMISSION To fully enable transparent data transmission, an 8-bit character format is used. The characters are transmitted asynchronously with 1 start bit and 1 stop bit. No bit is used for parity checking. The 8-bit code is identified by b 8, b 7, b 6, b 5, b 4, b 3, b 2 and b 1, where b 8 is the most significant bit (MSB) and b 1 is the least significant bit (LSB). The bit combinations represent integers that range from 0 to 255, where b 8 has a binary weight of 128 and b 1 has a binary weight of 1. The character format in the asynchronous operation is shown in Table 1. Table 1. Asynchronous character transmission 6/87

13 Binary 1 Binary 0 ST b 1 b 2 b 3 b 4 b 5 b 6 b 7 b 8 SP Start bit Stop bit The least significant bit b 1 of the character is transmitted first. 3.5 TRANSMISSION SPEED The Nokia M2M module supports the data transfer baud rates listed in Table 2. The baud rate is preselected in the system configuration phase and cannot be changed dynamically during the operation. Table 2. Supported baud rates Baud rate 9600 bit/s bits/s bits/s bits/s bits/s 7/87

14 4 DATA LINK LAYER 4.1 OVERVIEW This chapter defines the DLL that is used for communication between the Nokia M2M module and the AM. The link protocol is full-duplex in the sense that data exchange is allowed simultaneously to both directions after the line has been reserved for communication as specified in the Chapter REQUIREMENTS FOR THE PHYSICAL LAYER The data link layer requires that the physical layer carries 8 bit characters (octet) transparently (see Chapter 3.4 for details). Loose timing requirements for the physical layer are set by the system parameters of the DLL. 4.3 DATA LINK PROTOCOL ELEMENTS Terminology The DLL terminology is based on the CCITT T.50 recommendation (International Alphabet No. 5 - IA5). The DLL uses a subset of control characters in the range 00h and 1Fh as defined in T.50. Only the control characters defined in the following chapters have an effect on the function of the link layer. The data part (higher layer section) of a link layer message is fully transparent and may contain any 8-bit characters Packet format The general packet format of the start-stop, octet-oriented mode is shown in Table 3. The packet begins with a start sequence, using IA5 control characters SYN-DLE-STX. The start sequence is followed by a header field with a constant information length of 4 octets before DLE stuffing. The packet ends with a stop flag, using IA5 control characters DLE-ETX. The stop flag is followed by a twooctet FCS. 8/87

15 Table 3. General data link layer packet format SYN Start flag character DLE Start flag character STX Start flag character Header Header field of the packet body 4 octets 8.. Data Data field of the packet body n octets N DLE Stop flag character 1 N ETX Stop flag character 2 N-1 FCS 16 bit cyclic redundancy check sum N 2 octets The data field, when present, contains transparent data. To transmit transparent user data, a method called DLE stuffing is required. This method is described in Chapter The packet body (header and data) and DLE-ETX stop flag are included in the FCS calculation. The start sequence and all DLE control characters used to maintain data transparency are excluded from the FCS calculation Transparency The transmitting entity examines the packet body (header and data fields) and inserts a DLE control character immediately following any occurrence of a DLE character. The DLE used in the start and stop flags is not doubled. The receiving entity examines the packet body and discards the second DLE of a two-octet DLE-DLE sequence Error check Cyclic Redundancy Check (CRC) is used for header and data protection. It is defined by the generator polynomial: G(x) = x 16 + x 15 + x The FCS comprises 16 bits and is used for error detection. The check bits will be the 1 s complement of the modulo 2 sum of: 9/87

16 the remainder of x k (x 16 +x 15 +x 14 +x 13 +x 12 +x 11 +x 10 +x 9 +x 8 +x 7 +x 6 +x 5 +x 4 +x 3 +x 2 +x +1) divided modulo 2 by the generator polynomial G(x) where k is the number of bits to protect the remainder of the division modulo 2 by the generator polynomial G(x) of the product of x 16 by the content of information to protect, excluding the FCS field. As a typical implementation at the transmitter, the initial content of the register of the device computing the remainder of the division is preset to all ones (1) and is then modified by division by the generator polynomial G(x) of the information to be protected; the 1 s complement of the resulting remainder is transmitted as the 16 check bits. At the receiver, the initial content of the register of the device computing the remainder is preset to all ones (1). The final remainder (after multiplication by x 16 and then division by the generator polynomial G(x) of the incoming protected bits, including the FCS) will be x x 0 = in the absence of transmission errors. The FCS bits are mapped on FCS octets so that the x 15 bit is the b 1 bit of the first octet and the x 7 bit is the b 1 bit of the second octet. Note: A simple and fast 8-bit oriented algorithm for FCS calculation, suitable for implementation in both a microprocessor-controlled radio unit and in a standard PC, is given in Appendix E: An example of parallel FCS calculation Elements of a data link layer procedure The header field defines the data link peer-to-peer protocol functions. The header field may be followed by a variable length data field, which contains transparent user data. The header has a constant length of 4 octets and contains information for the remote data link layer, but it can be used as an input for other layers. This information will not be transmitted over the radio path. The general header elements are as follows: Type indication Type-dependent parameters The type indication has a length of one octet and will be the first octet of the header. The type indication identifies the header field and encoding for the 10/87

17 remainder of the header field. Unused parameter fields are filled with 0x00 (IA5 character NUL). The following header types are specified: Link request (LR) Link transfer (LT) Link acknowledgement (LA) Link request format The link request (LR) format is used to establish (or re-establish) a connection between two entities with an active physical connection. LR packets have no data field. The header field structure of an LR packet is shown in Table 4. Table 4. Link request header field 1 LR Link Request Value 0x01 2 N1 Maximum length Range K Window size Standard 1, other values optional 4 VERSION Protocol version number System protocol For a definition of maximum length parameter N1, see Chapter The window size (k) defines the maximum number of pending LT packets, with a maximum data field length, that may be sent at a given time without waiting for an acknowledgement. The version number of the M2M System Protocol 2 is 129 (0x81) Link acknowledgement format The link acknowledgement (LA) format is used both to confirm the link establishment and to acknowledge LT packets. One LA packet may acknowledge multiple LT packets. LA packets have no data field. The header structure of an LA packet is shown in Table 5. Table 5. Link acknowledge header field 1 LA Link Acknowledgement Value 0x02 2 N(R) Rx sequence number Binary, modulo N(k) Rx credit number Binary, modulo Reserved Reserved NUL 11/87

18 The receive sequence number N(R) is the number of the next expected LT packet. The receive credit number N(k) is the number of LT packets that can be sent before the sender must wait for an acknowledgement. The ready or busy status of the receiver is controlled by the receive credit number N(k). The LA packet credit parameter contains the number of LT packets the receiver is able to accept at the moment of LA transmission. The zero (0) credit value stops the transmission of a new LT by the sender Link transfer packet The link transfer (LT) packet is used to transfer higher layer data in sequentially numbered data fields. The data field contains transparent user data up to the field length defined by N1 negotiated during the establishment phase. The header structure is shown in Table 6. Table 6. Link transfer header field 1 LT Link Transfer Value 0x04 2 N(S) Tx sequence number Binary, modulo AR Acknowledgement request 0/1 4 Reserved Reserved NUL The send sequence number N(S) is the number of the data field. This number is incremented in a modulus manner with each transmitted LT packet. Values 0 and 1 are used with the acknowledgement request parameter AR with the following definitions: 0 no special acknowledgement requested 1 this LT packet has to be acknowledged immediately Variables and sequence numbers All LA and LT packets are sequentially numbered, and in each entity there are corresponding state variables, which may have any value within the range of 0 to m-1, where m is the modulus of the sequence numbers. The modulus is 256 and all arithmetical operations on defined state variables and sequence numbers are affected by the modulo 256 operation. LT packets contain a send sequence number N(S). If an in-sequence LT packet is designated for transmission, N(S) is set equal to the send state variable V(S). 12/87

19 LA packets contain a receive sequence number N(R), the expected N(S) of the next received LT packet. The value of N(R) indicates that all correctly received LT packets are acknowledged up to (and including) N(R)-1. If an LA packet is designated for transmission, N(R) is set equal to the receive state variable V(R). The send state variable V(S) denotes the sequence number of the next insequence LT packet to be transmitted. The value of V(S) will be incremented by 1 with each successive LT packet transmission, but it cannot exceed the N(R) of the last received LA packet by more than the maximum number of pending LT packets (the value of the window size k). The receive state variable V(R) denotes the sequence number of the next insequence LT packet expected to be received. V(R) will be incremented by 1 with each correctly received LT packet whose N(S) equals V(R). The receive credit state variable R(k) denotes the number of LT packets the receiver is able to receive. The number of received LT packets not acknowledged (plus R(k)) cannot be greater than the window size k. R(k) is updated as often as required and represents the receiver's ability to accept LT packets. LA packets contain a receive credit number N(k). If an LA packet is designated for transmission, N(k) is set equal to a receive credit state variable R(k). This N(k) indicates that the entity is able to receive LT packets numbered up to (and including) N(k)+N(R)-1. The send state credit variable S(k) denotes the number of LT packets the sender is able to transmit without additional credit from the receiver. The number of LT packets that are not acknowledged cannot be greater than the last received N(k), which is in the range from zero to the window size k. The value of S(k) is decremented by 1 each time a new LT packet is transmitted. Upon initialization, the state variables are set as follows: V(S) set to 1 V(R) set to 1 R(k) set to k S(k) set to DATA LINK PROTOCOL DESCRIPTION The following two main states are defined with the data transfer protocol: 'Data link establishment' or 'reset_wait' and 'link_wait' 13/87

20 'Data transfer ready' or 'ready' The data link establishment procedure begins after the power is turned on or after a reset. After link establishment the entity is in the data transfer phase and is able to send or receive LT packets. Once the power is turned on, a receiver must be capable of decoding and interpreting the header field of an incoming message and checksum. It may discard the data field if it is not ready to receive data. The receiver will discard a received packet if it is faulty (for example if the checksum does not match). This protocol in SDL format can be found in Appendix F: SDL representation of the Data Link Layer Link establishment phase procedure The entities at either end of a physical connection may initiate the link establishment procedure at any time, and both entities may do so simultaneously. The originating entity (the initiator) begins the procedure of the link establishment phase. The receiving entity is ready to respond to protocol messages and performs parameter negotiation with its internal parameters. The receiving entity examines the LR packet parameters it receives, compares them to its internal parameters, and determines the parameter values that are suitable for both ends. The suitable parameter value is the lower of the two compared values and it is set as the parameter value that will characterize the connection. If the entity is in the data transfer phase and it receives an LR packet, it enters the link establishment phase. It also enters the link establishment phase when switched on or reset. During the link establishment phase, all data transfer is blocked and all data buffers within the data link layer are cleared Sending LR packets The link establishment procedure is initiated by sending an LR packet with the highest internal parameter values of the originating entity. An entity transmits an LR packet, enters or stays in the link establishment phase, and starts or restarts time control T0 and stop time controls T1, T2, T3 and T4, if any of the following conditions occur: Power is switched on 14/87

21 The entity detects a link failure with a need for re-establishment The higher layer signals a reset request The entity receives an LT packet in the link establishment phase The entity receives an LR packet in the data transfer phase Time control T0 expires Receiving LR packets If the entity is in the link establishment phase and it receives an LR packet, it performs parameter negotiation. If the parameters are acceptable and the entity has sent an LR packet with suitable parameters at least once in this link establishment phase, it: 1. Stops time control T0, 2. Initializes internal variables and clears data buffers, 3. Transmits an LA packet, 4. Starts time control T3, and 5. Starts time control T4. If the entity is in the link establishment phase and it receives an LR packet with non-acceptable parameters, or the entity has not sent an LR packet in this link establishment phase, it: 1. Transmits an LR packet with suitable parameters, and 2. Starts time control T Receiving LA packets If an entity receives an LA packet in the link establishment phase and has been sent an LR packet at least once in the current link establishment phase, it: 1. Stops time control T0, 2. Initializes internal variables, setss(k) to N(k), and clears data buffers, 3. Sends an LA packet, 4. Starts time control T3, 5. Starts time control T4, 6. Signals data transfer ready to the higher layer, and 7. Enters the data transfer phase. 15/87

22 If an entity receives an LA packet in the link establishment phase and has not been sent an LR packet in this link establishment phase, it: 1. Sends an LR packet, and 2. Starts time control T Data transfer phase procedure After completion of the data link establishment, the entities are in the data transfer phase and are able to exchange data using LT and LA packets. LT packets have a data field that cannot contain more user data than what is defined by N1 (see Chapter 4.5.5) Sending LT packets When an entity has user data to transmit and the remote entity is ready to receive data, it transmits an LT packet with N(S) equal to its send state variable V(S). The value of V(S) is incremented and the value of S(k) is decremented by 1 (modulo 256). When the transmission of a new LT packet is completed, time control T1 is restarted, and the retransmission counter C1 is reset. If S(k) = 0, the entity is not allowed to send LT packets until S(k) is updated to a value other than zero by an incoming LA packet. The entity may set the AR bit to '1' if it requires immediate acknowledgement. It is recommended that the AR bit is set to 1 when S(k)= Receiving LT packets If an entity is ready to receive data and it receives a valid LT packet whose N(S) equals its receive state variable V(R), the entity accepts the data, increments its V(R) by 1 (modulo 256), and restarts timers T2 and T4. The receiving entity discards the data field of an LT packet if: N(S) is not equal to the current V(R), or The receive credit R(k) equals zero and the entity is not ready to receive user data Sending LA packets An entity sends an LA packet with N(R) equal to its receive state variable V(R) and with N(k) equal to its receive credit variable R(k) to: 16/87

23 Acknowledge one or more valid LT packets that is has received, or Report a condition that requires a retransmission of one or more LT packets, or Inform the remote entity about the ability to accept additional LT packets. An LA packet is sent, timer T2 is stopped, and timer T3 is restarted, if one of the following conditions occurs: An out-of-sequence LT packet in which N(S) is not equal to V(R) is received, or An LT packet is received without credit (R(k) equals zero (before update), or Timer T2 has expired, or R(k) is updated from zero to a higher value, or An LT packet is received with AR set to one (immediate acknowledge request), or Timer T3 expires. An LA packet may be sent each time the entity receives an LT packet, when R(k) is updated to a higher value than the last-used N(k), or when R(k) is decreased to zero Receiving LA packets When an LA packet is received, timer T4 is restarted and the value of N(R) is considered as an acknowledgement for all pending LT packets with N(S) up to (and including) the received N(R)-1. If N(R) equals V(S) (acknowledging all pending LT packets), the retransmission counter C1 is reset and the time control T1 is stopped; otherwise T1 is restarted. The credit variable S(k) is set equal to the value of N(k) minus the number of pending LT packets. S(k) = N(k)-(V(s)-N(r)) Retransmission of LT packets Retransmission of pending LT packets is initiated and the retransmission counter C1 is incremented, if one of the following conditions occurs: A received LA packet has N(R) equal to the last received N(R), or Timer T1 expires Retransmission starts with the first in-sequence, unacknowledged LT packet. Time control T1 is started or restarted after transmission of each LT packet. 17/87

24 If an acknowledgement is received for specific LT packets (during the retransmission of packets) due to the above conditions, the acknowledged packets are not retransmitted Link failure detection An entity assumes a connection failure and it performs a data link reset (see Chapters and ) when any of the following conditions occurs: The retransmission counter C1 reaches the maximum number of retransmissions N2, or The received acknowledgement packet sequence number N(R) is outside of the expected range N(R), is less than the last received acknowledge packet number, or is higher than the transmission state variable V(S) value), or Timer T4 expires The data link reset is signalled to the higher layer Receiving LR packets If an entity receives an LR packet during the data transfer phase, it will execute a data link reset (Chapters and ). The data link reset is signalled to the higher layer. 4.5 DATA LINK SYSTEM PARAMETERS Time control T0 Time control T0, establishment phase retry timer, specifies the time the entity waits before the retransmission in the link establishment phase is initiated. The initial value of T0 is 500 ms. The value of T0 may be increased, due to a prolonged link establishment phase, up to 15 s.time control T1 Time control T1, transfer phase retry timer, specifies the time the entity waits before the retransmission in the data transfer phase is initiated. The period of time T1 depends on the transmission speed of the physical connection. In the data transfer state, the period is determined by the following formula: T1 > 2 x (L lt + L la ) / R where: L lt is the length of an LT packet in bits (after DLE stuffing). The length depends on the value of N1. 18/87

25 L la R is the length of an LA packet in bits is used data rate in bits per second Typical values for T1 are shown in Table 7. Table 7. Time control T1 values* R N1 = 0 N1 = 10 N1 = 100 N1 = s 1.0 s 7.0 s 17.0 s s 0.6 s 3.5 s 8.6 s s 0.3 s 1.8 s 4.3 s s 0.2 s 0.9 s 2.2 s s 0.1 s 0.6 s 1.5 s * The values in Table 7 include DLE stuffing Time control T2 Time control T2, acknowledge timer, is the time within which an acknowledgement must be sent. The maximum value of T2 is T1 minus twice the length of an LA packet. When an entity sends an LA packet each time after receiving an LT packet, the time control T2 actions may not be required Time control T3 Time control T3, activity timer, specifies the time an entity waits before the transmission of an LA packet is initiated to report the receiver credit. T3 has a maximum value of 15 seconds Time control T4 Time control T4, link failure detection timer, specifies the time an entity waits to receive an LA or an LT packet before a failure of the connection is assumed and a data link reset is initiated. The link failure delay time T4 is a period greater than N3 x T The maximum length parameter N1 The maximum length parameter N1 defines the maximum data field length that can be sent with the link transfer packet. This parameter may have values between 0 and 255. The maximum data field length n octet in octets is calculated as follows: 19/87

26 n octet = 16 x (N1 + 1) With N1=0 the maximum number of data octets is 16, and with N1=255 the maximum data field length is The data field length chosen must be large enough for the longest NLL message used. Note: Due to DLE stuffing the maximum length of the sent data can be 2 x 4096 (if each payload byte is 0x10). For more information on the usage of the DLE control characters, see Chapter The maximum number of retransmissions N2 The value of N2 specifies the maximum number of attempts an entity makes to complete LT packet transmissions to the correspondent entity. The value of N2 is The maximum number of activity timeouts N3 The value of N3 specifies the maximum number of timeouts before a link activity failure is detected. N3 and T3 are used to define the value of the link failure delay timer T4. The value of N3 will be at least 2. 20/87

27 5 NETWORK LINK LAYER 5.1 OVERVIEW The NLL makes it possible for the protocol stack user to control sockets and wireless links. It also makes it possible to implement the Socket API on top of the M2M System Protocol NETWORK LINK LAYER PACKET FORMAT NLL packets are used to carry protocol primitives over the M2M System Protocol DLL link. An NLL packet contains a packet header, packet body, and an extension field. All parts of an NLL packet will be transmitted in one M2M System Protocol Link Transmit (LT) message. The maximum size of an NLL packet is limited by the M2M System Protocol frame, which can be no more that 4096 bytes long. The extension field is located after the message body. An extension mechanism is specified in the M2M System Protocol 2 to be used by future versions of the Nokia M2M module. Every NLL packet contains the extension field length value, even if there is no extension data in the packet. If the extension field is not included in the NLL packet, the extension field length value is zero (0). When the M2M System Protocol 2 is used, every protocol entity must be able to receive packets that have unknown extension data. That is, every protocol entity must be able to handle packets even if their extension field length value is other than zero (0). The ability to receive packets with unknown extension data is required for future M2M System Protocol 2 compatibility. Max bytes LT header 0x22 header Message type -specific body Extension field LT trailer, fcs Example packet (No payload No extension zz zz for RESET) field Figure 1. LT message DLL NLL The same packet format is used irrespective of the packet direction. Since the M2M System Protocol 2 incorporates a packet numbering and cyclic 21/87

28 redundancy check (CRC) checksum mechanism for LT packets, they do not have to be implemented in the packet format Data types Data in protocol packets is transmitted in 8 bit octets. Table 8. NLL packet data types Data type name Length byte, octet 1 byte - Description short 2 bytes Most significant byte first. ushort 2 bytes Most significant byte first. Unsigned. int 4 bytes Most significant byte first. long 8 bytes Most significant byte first. string 5 - n bytes Four bytes length (uint) followed by a string body (ASCII characters) with the terminating null character 0x00. The length includes the terminating null. The length of an empty string is 1 and the body has only the terminating 0x00. For example the string hello is encoded as: 0x00 0x00 0x00 0x06 0x68 0x65 0x6C 0x6C 0x6F 0x00 Fixed size octet sequence, byte array 0 - n bytes The last zero (0) is the terminating null character Packet header Each protocol packet has a fixed 8-byte packet header. Operation requests and operation responses always have the same packet type byte. Req/resp byte is used to do differentiate operation requests from operation responses. Table 9. NLL packet header Packet header field Length Description Magic 1 byte The M2M System Protocol 2 identifier is 0x22. 22/87

29 Packet header field Length Description Operation code 1 byte The available operation codes are listed in Appendix A: Operation codes. Req/resp 1 byte The possible values are 0 (request) and 1 (response). Flags 1 bytes Packet flags are reserved for future use. The value must be set to 0. Packet sequence number (PSN) Extension field length Body length 2 bytes, ushort 2 bytes, ushort 2 bytes, ushort Packet sequence number, modulo 0xFFFF. Length of the extension field. 0x00 0x00 if the extension field is not present. The extension field length does not include the message body. Length of the message body without the possible extension field. 0x00 0x00 if the message body is not present. The packet header is not included into the body length. The following examples illustrate the NLL packets RESET and RESET_RESP (in hexadecimal). RESET: RESET_RESP: Extension field The M2M System Protocol 2 specifies an extension mechanism to be used by future versions of the Nokia M2M module. Table 10. NLL packet extension field Extension field contents Length Description Extension elements Bytes An array of extension elements. Each element has a specific structure described in Table /87

30 Extension elements If the receiving entity receives a packet with an extension field and it does not need extensions, it can ignore the extension field. There is no need to parse elements. However, if the receiving entity receives a packet with extensions and it needs to parse specific extension tags, it must parse the whole extension array. The receiving entity can use the extension tag ID to identify the correct extension elements. If the receiver knows the structure of the extension element, it can parse the extension element data. If the receiver does not recognize the element, it must use data length value to skip the element data and read the next element. Extension data may be in whatever format; it may or may not use data types described in this document. Also, extension elements may be in whatever order inside the extension field. Table 11. NLL packet extension element Extension element contents Length Description Extension tag ID int Tag identifier. Data length ushort Length of the following data (extension tag ID is not included). If data is missing, the data length is 0. Data bytes Extension element data. The extension tag ID specifies the structure of the extension element data. NLL packet example of an extension field with two extension elements: In this example the first element has extension tag ID value 1, and data length is two bytes. The second element has extension tag ID 9, and data length is one byte. The extension field length for this operation packet containing only these extension elements is 00 0F Network Link Layer packet examples In this example packet the operation code is 0xEF, the message body is two bytes long and there are no extensions. 22 EF FE FE 24/87

31 In this packet the message body has four bytes (AA, AA, AA, AA) and the packet has an extension field with one extension element. 22 EF AA AA AA AA PROTOCOL PRIMITIVES Each protocol primitive consists of a protocol request message and a related response message. The sender must not send another operation until it has received a response for the sent message. An operation message may include operation arguments. The returned response message may be empty or include return values. Each message has a packet sequence number (PSN) that is used to match operation messages and their responses together. Each protocol entity must keep count of two packet sequence numbers: receiver PSN and sender PSN. If the M2M System Protocol 2 receives a packet with an unexpected PSN, it must reset the connection. If NLL fails to send an operation primitive across DLL, it must reset the link. No message loss is allowed without issuing a RESET. The M2M System Protocol 2 has operations and notifications. Operations are usually executed from the AM to the Nokia M2M module, and notifications are sent from the Nokia M2M module to the AM. Operations are named XXXX and notifications XXXX_NOTIFICATION. Notifications are handled as normal operations and the receiver must respond to them. Responses are named XXXX_RESP. One operation at the time limits scalability, but simplifies protocol implementation. In the following sequence diagram DLL is displayed. In later diagrams DLL is omitted for brevity. 25/87

32 User NLL A DLL A DLL B NLL B operation() send (OPERATION) LT(OPERATION) LA receive (OPERATION) Execute operation receive_psn++ operation_ok_ind() receive (OPERATION _RESP) LT (OPERATION _RESP) LA send (OPERATION _RESP) Figure 2. OPERATION OPERATION_RESP sequence 5.4 RESET AND STARTUP RESET Direction: Bidirectional between the Nokia M2M module and the AM. Description: NLL sends a RESET message immediately after it has received the LINK_OK indication from DLL after reboot. When the receiver receives this message, it knows that the sender has lost all state information and all pending requests will fail. All open server sockets (binds) must be re-initialized by the sender, and before it can be done, the RESET receiver must close them. When the receiver receives the RESET message, it must send RESET_RESP after the clean up is completed. After RESET, the first request the sending protocol entity makes must be sent with PSN 1. Respectively, the receiving protocol entity must expect that the first request it receives comes with PSN 1. Note: The request made after RESET is not the only request that can be sent with PSN 1. Both of the PSN numbers can wrap over after value 0xFFFF and start again from 0 without RESET. 26/87

33 A protocol entity can also send RESET as an indication of a fatal error situation. A protocol entity must send RESET if the other protocol entity sends a protocol primitive using an unexpected packet sequence number. Because the data link between the two entities is reliable, the unexpected packet sequence number is seen as a fatal error. The receiver can send a response only after its NLL is in ready state. The sender must not send other operations until it has received a response for the RESET message. However, the sender must handle incoming operation requests even if it is waiting for the RESET_RESP message. This is done because at the system start-up both ends may send RESET simultaneously and the start-up does not continue if neither the sending end nor the receiving end handles the requests coming from the other end. When the Nokia M2M module receives a RESET from the AM, it must immediately close all server and client sockets and links opened by the AM. When the receiving entity receives the RESET message, it must do the following: 1. Notify the protocol user 2. Clear state variables, SEND_PSN and RECEIVE_PSN 3. Send RESET_RESP back to the sending entity If the sending entity does not receive a RESET_RESP message within a specified time frame, it must send the RESET message again until it receives the RESET_RESP message. Protocol startup cannot proceed further until the resetting entity has received an acknowledgement for the RESET message. While the Nokia M2M module is handling the received RESET message, it cannot send any events to the AM. If the AM has sent a RESET message, it is not interested in other events (such as link closing) RESET_RESP The receiving entity has notified the sending entity of a reset situation. The protocol user is also notified. 27/87

34 AM DLL A DLL B Nokia M2M module Start-up link_ready_ind send (RESET) LT(RESET) LA receive(reset) send (RESET_RESP) Clear packet sequence numbers, abort pending transactions, close all sockets. LT(RESET_RESP) receive (RESET_RESP) LA Ready to continue initialization. Figure 3. RESET RESET_RESP sequence Both ends resetting simultaneously A situation in which both ends reset at the same time is typical for start-up. A simultaneous reset illustrated in Figure 4 also provides a good example of how NLL A must be able to process an incoming request from NLL B while waiting a response to its own request. 28/87

35 NLL A NLL B RESET This is a typical start situation where one side sends a RESET and receives a RESET from the other end before receiving the RESET_RESP message. RESET RESET_RESP RESET_RESP Both NLLs ready Figure 4. The AM and the Nokia M2M module resetting simultaneously 5.5 LINK CONTROL Link control is not a part of the Socket API, but it is provided for the AM. Link control allows only the opening and closing of a preconfigured link. That is, the M2M System Protocol 2 does not include messages for changing link configuration. When the AM opens a link, the time that the opening-process takes depends on the connection that is used. The diagram in Figure 5 illustrates a typical successful link-opening process where the user specifies the connection ID of the connection he wants to open. When the AM receives the user s request, it opens the specified connection and returns the link ID of the opened link. In the diagram the NLL and DLL levels have been simplified as one unit. 29/87

36 User AM Nokia M2M module open_a_link(connection_id) User wants to open a link and specifies the connection_id. LINK_OPEN(connection_id) LINK_OPEN_RESP(link_id) The Nokia M2M module starts to open the link. LINK_STATUS _NOTIFICATION(link_id) The link is opened successfully. LINK_STATUS _NOTIFICATION_RESP link_id The link was opened succesfully and a link_id is returned to the user. Figure 5. Successful link-opening sequence A similar step sequence is used to close a link LINK Direction: From the AM to the Nokia M2M module. Description: Verifies the existence of a preconfigured link and the link status. The LINK_RESP message returns some configuration information. Table 12. LINK message Data type Name Description 30/87

37 Data type Name Description int Connection ID Connection index to be checked LINK_RESP Direction: From the Nokia M2M module to the AM. Description: A response message to the LINK message. Returns the required connection information. Table 13. LINK_RESP message Data type Name Description int Connection ID The same connection ID that was used in the LINK message. int Status If the status is NO_BEARER, there is no configuration for the specified connection ID. If the status is LINK_OK, the requested link is configured. octet Bearer* If the status is LINK_OK, this part of the message indicates the type of the configured bearer. The available bearer types are: string Server address SCKT_BEARER_GPRS, SCKT_BEARER_CSD, SCKT_BEARER_SMS If the link is not configured, the bearer value is 0 (unspecified). Server or proxy address. Returns the server address, if the server is set for this connection. If the server is not set, returns an empty string. The AM can use this, for example, as HTTP proxy address. short Server port If the server address is empty, the server port value is 0. * The available bearer types are described in Appendix B: Protocol constants LINK_OPEN Direction: From the AM to the Nokia M2M module. 31/87

38 Description: Sent by the AM to open a link over one of the preconfigured connections. The LINK_OPEN_RESP message returns a link ID that can be used later with the Socket API. Call returns after the link establishment has started. An incoming LINK_STATUS_NOTIFICATION message indicates whether or not the link opening succeeded. Note: If the AM wants for the Nokia M2M module to open a preconfigured default connection, it must use the USED_CONNECTION as a connection ID. Table 14. LINK_OPEN message Data type Name Description int Connection ID Connection index of the connection to be opened. The ID must point to one of the bearers that have been preconfigured to the Nokia M2M module LINK_OPEN_RESP Direction: From the Nokia M2M module to the AM. Description: Sent by the Nokia M2M module to notify the status of the requested link. The LINK_OPEN_RESP may notify that the requested link was already open. The status SCKT_NETWORK_OPEN_IN_PROGRESS indicates that link opening is currently in progress, and that the AM must wait for a LINK_STATUS_NOTIFICATION holding a status SCKT_NETWORK_OPENED. The status of the LINK_STATUS_NOTIFICATION might also be an error-code, which indicates that the opening has failed. If the LINK_OPEN_RESP holds the status SCKT_NETWORK_OPENED, the caller does not have to wait for the LINK_STATUS_NOTIFICATION. Table 15. LINK_OPEN_RESP message Data type Name Description int Link ID A unique link ID. int Status* SCKT_NETWORK_OPENED SCKT_NETWORK_OPEN_IN_PROGRESS or 32/87

39 Data type Name Description SCKT_EFAULT or SCKT_NETWORK_BEARER_NOT_AVAILABLE * The socket status indications are described in Appendix B: Protocol constants LINK_STATUS_NOTIFICATION Direction: From the Nokia M2M module to the AM. Description: Sent by the Nokia M2M module to notify about open or closed links. The status codes SCKT_NETWORK_OPENED and SCKT_NETWORK_RESUMED indicate that the link can be used for data transmission. All other status codes are error cases in which data transmission does not work over the specified link. Table 16. LINK_STATUS_NOTIFICATION message Data type Name Description int Link ID The link ID of the opened link. int Status* SCKT_NETWORK_OPENED or SCKT_NETWORK_CLOSED or SCKT_NETWORK_DISCONNECTED or SCKT_NETWORK_OPEN_IN_PROGRES or SCKT_NETWORK_PPP_NEG_FAILED or SCKT_EFAULT or SCKT_NETWORK_BEARER_NOT_AVAILABLE or SCKT_NETWORK_RESUMED or SCKT_NETWORK_SUSPENDED * The socket status indications are described in Appendix B: Protocol constants LINK_STATUS_ NOTIFICATION_RESP Direction: From the AM to the Nokia M2M module. Description: Acknowledgement for the LINK_STATUS_NOTIFICATION LINK_CLOSE Direction: From the AM to the Nokia M2M module. 33/87

40 Description: Sent by the AM to close the specified link. The Nokia M2M module closes the link and sends a LINK_CLOSE_RESP to the AM. After sending the response the Nokia M2M module sends a LINK_STATUS_NOTIFICATION with the status SCKT_NETWORK_CLOSED. The caller must wait for the notification. Table 17. LINK_CLOSE message Data type Name Description int Link ID Link ID of the link to be closed LINK_CLOSE_RESP Direction: From the Nokia M2M module to the AM. Description: Acknowledges that the link closure has started. Table 18. LINK_CLOSE_RESP message Data type Name Description int Link ID Link ID of the closed link. 5.6 SOCKET CONTROL OPERATIONS The socket control operations are used to handle both TCP and UDP sockets. Some response messages echo back operation request values to help protocol implementation in the AM. When the identity values are echoed back there is less need to keep a protocol state Local addressing The addressing between the AM and the Nokia M2M module is done using local sockets. The SCKT_LINK_LOCAL link ID is used if the connection to the AM is from Nokia M2M module ORB or from the IMlet located in the Java TM virtual machine of the Nokia M2M module SOCKET Direction: From the AM to the Nokia M2M module. 34/87

41 Description: Reserves a specified socket from the Nokia M2M module. Sets up a protocol to be used, and associates the link with the socket. Note: This SOCKET message cannot be used to open a specific link. The AM must always remember to close all sockets that it has opened or accepted. A received RESET message is the only exception of this rule because when the RESET message arrives, all sockets have already been closed. Table 19. SOCKET message Data type Name Description int Address format* SCKT_AF_INET or int Type* SCK_STREAM or SCKT_AF_INET6 (also called domain). SCK_DGRAM int Protocol 0, TCP or UDP. The AM must use zero (0) as the default. Using zero selects the default protocol based on the socket type. int Link ID Selected link ID. For more information, see Chapter 5.5. The link ID can be set to SCKT_LINK_ANY to create a server socket for incoming connections. * The socket types and address formats are described in Appendix B: Protocol constants SOCKET_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the Nokia M2M module that notifies the status of the socket that is being created. Table 20. SOCKET_RESP message Data type Name Description int Status* SCKT_OK or SCKT_EAFNOSUPPORT or SCKT_EMFILE or SCKT_ENOBUFS or SCKT_EPROTONOSUPPORT or 35/87

42 Data type Name Description int Socket ID SCKT_EPROTOTYPE or SCKT_ESOCKTNOSUPPORT or SCKT_ENETDOWN Specifies the socket identifier if the socket status is SCKT_OK. Otherwise the value is 0. The socket ID is used later in socket operations. * The socket status indications are described in Appendix B: Protocol constants SOCKET_CLOSE Direction: From the AM to the Nokia M2M module. Description: Closes a socket. The specified socket ID is invalid after the socket is closed. No operations can be done using the socket ID of the closed socket. Table 21. SOCKET_CLOSE message Data type Name Description int Socket ID Socket ID for the socket to be closed SOCKET_CLOSE_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the Nokia M2M module that notifies the status of the socket that is being closed. Table 22. SOCKET_CLOSE_RESP message Data type Name Description int Status* SCKT_OK or SCKT_ ENOTSOCK int Socket ID Socket ID for the closed socket. * The socket status indications are described in Appendix B: Protocol constants BIND Direction: From the AM to the Nokia M2M module. 36/87

43 Description: When the AM wants to receive data from a certain port, it first sends a bind message to the terminal. The AM must specify the protocol that is used and the port that it wants to listen to. Note: Even if the AM specifies an IP address in the BIND message, the Nokia M2M module does not use the specified address. The binding is always done to a address. The AM can bind twice in the same port only if it uses a different protocol for each bind. Table 23. BIND message Data type Name Description int byte Socket ID Address family Socket ID of the socket to be bound. IPv4 or IPv6. ushort Port Port (most significant byte first). 4 or 16 bytes IP address 4 byte address if IPv4 is used, 16 byte address if IPv6 is used. The address type is given when the socket is created BIND_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the Nokia M2M module that notifies the status of the socket that is being bound. Table 24. BIND_RESP message Data type Name Description int Status* SCKT_OK or SCKT_EADDRINUSE or SCKT_EADDRNOTAVAIL or SCKT_EAFNOSUPPORT or SCKT_EFAULT or SCKT_EINVAL or SCKT_ENOBUFS or SCKT_ENOTSOCK or 37/87

44 Data type Name Description SCKT_ENETDOWN int Socket ID The same socket ID that was used in the BIND message. * The socket status indications are described in Appendix B: Protocol constants LISTEN Direction: From the AM to the Nokia M2M module. Description: The AM sends this message when it wants to start listening to the incoming connections. Once the listening is started, is can be terminated only by closing the listening socket. Note: A precondition for the AM to be able to listen to the incoming connections is that the AM used the SCKT_LINK_ANY option when it created the socket. Table 25. LISTEN message Data type Name Description int Socket ID The socket ID of the listening socket LISTEN_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the Nokia M2M module that notifies whether or not the listening started successfully. Table 26. LISTEN_RESP message Data type Name Description int Status* SCKT_OK or SCKT_ENETDOWN or SCKT_EADDRINUSE or SCKT_EINVAL or SCKT_EISCONN or SCKT_ENOBUFS or SCKT_ENOTSOCK or 38/87

45 Data type Name Description SCKT_EOPNOTSUPP int Socket ID The socket ID of the listening socket. * The socket status indications are described in Appendix B: Protocol constants ACCEPT_NOTIFICATION Direction: From the Nokia M2M module to the AM. Description: The Nokia M2M module indicates that it is ready to receive connection requests by sending an ACCEPT_NOTIFICATION message. The ACCEPT_NOTIFICATION includes the address information of the remote end and the socket ID of the accepted socket. The AM can send data to the socket by using the specified socket ID. The link ID enables link control from the AM. The AM can, for example, accept the incoming socket, read the required data from the socket, close the socket and immediately after that close the link. However, the AM must not try to close SCKT_LINK_LOCAL or SCKT_LINK_ANY links because they are not opened via a wireless bearer. Note: The ACCEPT_NOTIFICATION message is not used with UDP sockets. Table 27. ACCEPT_NOTIFICATION message Data type Name Description int Listening socket ID The socket ID of the listening socket. Given in the LISTEN message. int Socket ID The socket ID of the accepted new socket. int Link ID Identifies the link from which the connection request came from. byte Addressing type IPv4 or IPv6. ushort Port Remote port. byte array Address, 4 or 16 bytes Remote IP address. 4 bytes if IPv4 used, 16 bytes if IPv6 used. 39/87

46 ACCEPT_NOTIFICATION_RESP Direction: From the AM to the Nokia M2M module. Description: The AM can only accept incoming connections. If it wants to close a connection it can immediately send a CLOSE message for the received socket ID. Note: The AM is responsible for closing all the sockets that it has received in an ACCEPT_NOTIFICATION message. Table 28. ACCEPT_NOTIFICATION_RESP message Data type Name Description int Status* SCKT_OK int Socket ID The same socket ID that was accepted in the ACCEPT_NOTIFICATION message. * The socket status indications are described in Appendix B: Protocol constants CONNECT Direction: From the AM to the Nokia M2M module. Description: Opens a connection to the remote target. The specified socket must be an unconnected stream or datagram socket. Table 29. CONNECT message Data type Name Description int Socket ID The socket ID of the socket to be connected. byte Address type IPv4 or IPv6. ushort Target port Target port to be connected. byte array Target IP address 4 bytes if the addressing type is IPv4, 16 bytes if the addressing type is IPv6. 40/87

47 CONNECT_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the Nokia M2M module to the CONNECT message. Note: If the CONNECT message is addressed to a datagram socket, the call returns immediately and no connection is established. Table 30. CONNECT_RESP message Data type Name Description int Status* SCKT_OK or SCKT_EADDRINUSE or SCKT_EADDRNOTAVAIL or SCKT_EAFNOSUPPORT or SCKT_ECONNREFUSED or SCKT_EINVAL or SCKT_EISCONN or SCKT_ENETDOWN or SCKT_ENETUNREACH or SCKT_ENOBUFS or SCKT_ENOTSOCK or SCKT_FLOW_CONTROL_ON_SUSPENDED or SCKT_ETIMEDOUT or SCKT_ECLOSING int Socket ID The same socket ID that was in CONNECT operation request. * The socket status indications are described in Appendix B: Protocol constants SEND Direction: From the AM to the Nokia M2M module. Description: The AM uses the SEND message to write data to a specified socket. The Nokia M2M module returns a SEND_RESP message to indicate the amount of data that was successfully sent. The socket the AM writes data to must be a connected stream or a datagram socket. A SEND SEND_RESP sequence is illustrated in Figure 6. 41/87

48 If the socket is an UDP socket, the data is sent in one UDP packet. The amount of data that is sent must be equal or less than one protocol maximum transfer unit (MTU). Table 31. SEND message Data type Name Description int Socket ID The socket ID of the socket to which the AM wants to write data. int Data length Octet sequence 0-n bytes Data to be sent. Length of the following data. The value is 0 if there is no data. AM protocol user AM NLL Nokia M2M module NLL send() SEND(length) FLOW CONTROL is ON. SEND_RESP(SCKT_FLOW_CONTROL_ON, bytes_sent) SCKT_FLOW_CTRL_NOTIFICATION FLOW CONTROL situation clears. SCKT_FLOW_CTRL_NOTIFICATION_RESP SEND(length) SEND_RESP(SCKT_OK, bytes_sent) Data sent. Figure 6. SEND - SEND_RESP sequence 42/87

49 SEND_RESP Direction: From the Nokia M2M module to the AM. Description: The Nokia M2M module sends a response after it has moved the data to the socket send buffer. The SEND_RESP message does not mean that the data has reached its final destination. If the send buffer is full, the operation returns the number of bytes that were successfully stored in the send buffer. If all the bytes are not stored, the AM must repeat the SEND message again until all the required bytes are stored to the socket send buffer. The status is SCKT_OK if the data was successfully delivered to the socket send buffer. If the SEND_RESP indicates that the number of sent bytes is zero (0), the AM must use the SEND message again. The zero reply indicates that the bearer is unable to transmit data from the buffer to the target. Bytes may be lost due to a temporary congestion/extensive packet drop problem that that the underlying protocol can solve. If the TCP protocol timeout fires, the Nokia M2M module returns a SCKT_ETIMEOUT error for the SEND message. If this error is received, the AM recognizes that the connection has broken and it closes the socket. The TCP timeout may last a couple of minutes. The socket may also return a SCKT_FLOW_CONTROL_ON or SCKT_FLOW_CONTROL_ON_SUSPENDED error code. This indicates that the TCP flow control is triggered. The AM must not send more data until the SCKT_FLOW_CTRL_NOTIFICATION arrives for the specified socket. Table 32. SEND_RESP message Data type Name Description int Status* SCKT_OK or SCKT_ENETDOWN or SCKT_ENOBUFS or SCKT_ENOTCONN or SCKT_ENOTSOCK or SCKT_EINVAL or SCKT_ECONNRESET or SCKT_ETIMEDOUT or SCKT_FLOW_CONTROL_ON or SCKT_FLOW_CONTROL_ON_SUSPENDED or SCKT_ENETUNREACH or 43/87

50 Data type Name Description SCKT_EOPNOTSUPP int Socket ID The same socket ID that was used in the SEND operation. int Bytes sent The number of bytes that are stored into the sockets send buffer. * The socket status indications are described in Appendix B: Protocol constants SENDTO Direction: From the AM to the Nokia M2M module. Description: The AM uses this operation to send UDP datagrams. Table 33. SENDTO message Data type Name Description int Socket ID The socket ID of the socket to which the UDP datagram is sent. int Link ID The link ID of the link that is used to send the UDP datagram. Each datagram can be sent using a different link. byte Address type Type of following target address (IPv4 or IPv6). ushort Target port The target port of the Nokia M2M module. byte array int Target address Data length IPv4 or IPv6 address. Octet sequence 0-n bytes Data to be sent. Length of the following data. The value is 0 if there is no data. * The socket status indications are described in Appendix B: Protocol constants SENDTO_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the Nokia M2M module to the SENDTO message. Table 34. SENDTO_RESP message Data type Name Description int Status* SCKT_OK or 44/87

51 Data type Name Description SCKT_ENETDOWN or SCKT_ENOBUFS or SCKT_ENOTCONN or SCKT_ENOTSOCK or SCKT_EINVAL or SCKT_ECONNRESET or SCKT_ETIMEDOUT or SCKT_FLOW_CONTROL_ON or SCKT_FLOW_CONTROL_ON_SUSPENDED or SCKT_ENETUNREACH or SCKT_EOPNOTSUPP int Socket ID The same socket ID that was in used in the SEND operation. int Bytes sent The number of bytes that were stored in the send buffer of the socket. * The socket status indications are described in Appendix B: Protocol constants SCKT_FLOW_CTRL_NOTIFICATION Direction: From the Nokia M2M module to the AM. Description: Sent by the Nokia M2M module to clear a flow control situation, if flow control was triggered with the SEND message. After the AM receives the SCKT_FLOW_CTRL_NOTIFICATION message, the flow control situation is cleared and the AM can send more data. Table 35. SCKT_FLOW_CTRL_NOTIFICATION message Data type Name Description int Socket ID The socket ID of the socket with the flow control situation. int Status* SCKT_FLOW_CONTROL_OFF * The socket status indications are described in Appendix B: Protocol constants SCKT_FLOW_CTRL_NOTIFICATION_RESP Direction: From the AM to the Nokia M2M module. Description: Sent by the AM to acknowledge the SCK_FLOW_CTRL_NOTIFICATION message. 45/87

52 Table 36. SCKT_FLOW_CTRL_NOTIFICATION_RESP message Data type Name Description int Socket ID The socket ID of the socket from which the flow control situation was cleared RECEIVE Direction: From the AM to the Nokia M2M module. Description: The AM uses this operation to receive data from a specified socket. When the AM sends a RECEIVE operation, the Nokia M2M module immediately returns a RECEIVE_RESP message. The returned RECEIVE_RESP notifies the socket status. If the status is SCKT_OK, the Nokia M2M module sends the actual data of the specified socket later in a RECEIVE_NOTIFICATION message and the AM replies with a RECEIVE_NOTIFICATION_RESP message. Note: The whole RECEIVE - RECEIVE_NOTIFICATION_RESP sequence is illustrated in Figure 7. If the AM wants to receive data in a single RECEIVE_NOTIFICATION message, it must define singlepart as the reception type. The length field specifies the maximum number of bytes that the AM is prepared to receive. The maximum receive unit (MRU) value is not used with the singlepart receive type. If the AM wants to receive all the data in one message, the size of the length field must be equal or less than one protocol MRU. The Nokia M2M module may return less data than the AM requests in the RECEIVE message. The AM does not receive all the data it requested, it must send the RECEIVE message again. If the AM wants to control the flow of the incoming data and still read more data than can be sent over a serial port in one data link layer message, it must use the multipart limited reception type. The Nokia M2M module sends data over the link in RECEIVE_NOTIFICATION packets until the maximum number of bytes that the AM is prepared to receive is reached or until a socket error occurs. The maximum number of bytes in each RECEIVE_NOTIFICATION is equal or less than what is specified in the MRU field. If a socket error is detected, the Nokia M2M 46/87

53 module sends a RECEIVE_NOTIFICATION message with an error status. After a socket error the Nokia M2M module does not send RECEIVE_NOTIFICATION messages anymore, and the AM must close the socket in question. When multipart unlimited is selected as a reception type, the Nokia M2M module sends data using multiple RECEIVE_NOTIFICATION messages and the socket operates in high performance push/streaming mode. The Nokia M2M module sends the RECEIVE_NOTIFICATION messages until the AM closes the socket in question. The maximum number of bytes in each RECEIVE_NOTIFICATION is equal or less than what is specified in the MRU field. The length field is not used with the multipart unlimited reception type If a socket error occurs or the AM closes the socket, the Nokia M2M module sends a final RECEIVE_NOTIFICATION with an error status. After the socket error, the Nokia M2M module does not send RECEIVE_NOTIFICATIONS anymore. It is recommended that one socket uses only one reception type. Changing the reception type from multipart unlimited to singlepart is not allowed because it can cause concurrence problems. That is, the AM can receive a new RECEIVE_NOTIFICATION message from the Nokia M2M module before the Nokia M2M module has received a new RECEIVE operation from the AM. Changing the reception type from multipart limited to singlepart is allowed only after the Nokia M2M module has finished sending the multipart. Singlepart can be changed to multipart after the Nokia M2M module has sent a RECEIVE_NOTIFICATION. The Nokia M2M module returns a SCKT_EFAULT if there is an attempt to execute a reception type change that is not allowed. When datagram is selected as a reception type, the Nokia M2M module immediately returns a RECEIVE_RESP message and once the datagram is received, it returns a RECEIVE_NOTIFICATION. The AM must call a BIND message for the datagram socket before it can read data from the socket. Table 37. RECEIVE message Data type Name Description int Socket ID The socket ID of the Nokia M2M module socket from which the AM wants to receive data from. byte Receive type 0 (singlepart) 1 (multipart limited) 2 (multipart unlimited) 47/87

54 Data type Name Description 3 (datagram) int Length The maximum number of bytes that the AM is prepared to receive. int MRU length The maximum number of bytes in a received data unit. One response message cannot contain more data than what is specified in the MRU length field RECEIVE_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the Nokia M2M module indicating the status of the socket that the AM requested. If the AM receives the SCKT_OK status, then it can expect RECEIVE_NOTIFICATION messages from the Nokia M2M module. If the AM receives an error, it must close the socket in question. Table 38. RECEIVE_RESP message Data type Name Description int Socket ID The socket ID of the socket from which the AM wants to receive data from. int Status* SCKT_OK or SCKT_ENETDOWN or SCKT_ENOTCONN or SCKT_ENOTSOCK or SCKT_EOPNOTSUPP or SCKT_ECONNRESET or SCKT_ETIMEDOUT or SCKT_ENETUNREACH or SCKT_ENOBUFS SCKT_EFAULT * The socket status indications are described in Appendix B: Protocol constants RECEIVE_NOTIFICATION Direction: From the Nokia M2M module to the AM. 48/87

55 Description: The Nokia M2M module uses the RECEIVE_NOTIFICATION message to transmit data to the AM. Note: After sending a RECEIVE_NOTIFICATION message, the Nokia M2M module waits for the AM to reply with a RECEIVE_NOTIFICATION_RESP message before it can send the next RECEIVE_NOTIFICATION message. If the AM receives a RECEIVE_NOTIFICATION with data length value 0, it indicates that the remote end has closed its socket and there is no more data to be received. When this occurs, the AM must close the socket in question. Table 39. RECEIVE_NOTIFICATION message Data type Name Description int Socket ID The socket ID of the socket from which the AM wants to receive data from. int Status* SCKT_OK or SCKT_ENETDOWN or SCKT_ENOTCONN or SCKT_ENOTSOCK or SCKT_EOPNOTSUPP or SCKT_ECONNRESET or SCKT_ETIMEDOUT or SCKT_ENETUNREACH or SCKT_ENOBUFS byte Address type IPv4 or IPv6. 4 or 16 bytes Sender address The IP address of the sender. ushort Sender port The port number of the sender. byte Receive type The receive type that was used in the RECEIVE message. byte Multipart complete If the value is true (1), all the requested data has been transmitted. If the value is 0, all the requested data has not been transmitted, and there are more RECEIVE_NOTIFICATION messages coming. int data length Specifies the length of the following data. The value is 0 if there is no data or the socket status is other than SCKT_OK. bytes 0-n bytes Data to be sent. * The socket status indications are described in Appendix B: Protocol constants. 49/87

56 RECEIVE_NOTIFICATION_RESP Direction: From the AM to the Nokia M2M module. Description: A return response from the AM to the RECEIVE_NOTIFICATION message. Table 40. RECEIVE_NOTIFICATION_RESP message Data type Name Description int Socket ID The socket ID of the socket from which the AM wants to receive data from. AM protocol user AM NLL Nokia M2M module receive() RECEIVE (singlepart, length, MRU) RECEIVE_RESP (SCKT_OK) Set socket to receive mode. RECEIVE_NOTIFICATION (SCKT_OK, data length, data) Data received from the socket. RECEIVE_NOTIFICATION_RESP Data returned to the protocol user. Figure 7. RECEIVE - RECEIVE_NOTIFICATION_RESP sequence GETHOSTBYNAME Direction: From the AM to the Nokia M2M module. 50/87

57 Description: The AM uses the GETHOSTBYNAME message to resolve host information from the Nokia M2M module. This is because a DNS service may not be negotiated for the link. Table 41. GETHOSTBYNAME message Data type Name Description int Link ID A valid link ID. string Domain name A domain name to be resolved from the domain name server GETHOSTBYNAME_RESP Direction: From the Nokia M2M module to the AM. Description: The Nokia M2M module uses the GETHOSTBYNAME_RESP to return the required host information. The values are valid only if return status is SCKT_OK. Table 42. GETHOSTBYNAME_RESP message Data type Name Description int Status* SCKT_OK or byte short Array of 4 or 16 byte arrays short Address type Address array length Address array Alias array length SCKT_HOST_NOT_FOUND or SCKT_TRY_AGAIN or SCKT_NO_RECOVERY or SCKT_NO_ADDRESS or SCKT_SERVICE_UNAVAILABLE IPv4 or IPv6. String array Aliases Array of ASCII strings. String Domain name Specifies the number of the following addresses. The value is 0 if no addresses are found. Each address is represented as 4 or 16 byte address. The number of addresses in an array is specified in the Address array length field. Specifies the number of the following aliases. The value is 0 if there are no aliases. Empty string if the domain name is missing. * The socket status indications are described in Appendix B: Protocol constants. 51/87

58 5.7 SPECIAL OPERATIONS These operations can be used to identify the Nokia M2M module GET_IDENTITY Direction: From the AM to the Nokia M2M module. Description: Sent by the AM to retrieve the identification and Home Location Agent (HLA) address of a specified Nokia M2M module. Used when the AM operates in the M2M System Mode and needs to publish a mobile IOR (mior). Other protocols can use the Nokia M2M module ID for identifying the Nokia M2M module in question and disregard the HLA information. This operation has no arguments GET_IDENTITY_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the AM to the GET_IDENTITY message. Table 43. GET_IDENTITY_RESP message Data type Name Description string string Nokia M2M module ID HLA address The ID of the specified Nokia M2M module. The ID can be, for example, term123@mydomain. The HLA IP address or hostname set for the specified Nokia M2M module. It can be, for example, or hla.mycompany.com. Empty string is used if the specified Nokia M2M module does not have a HLA configured or the HLA address is empty. short HLA port The HLA port set for the specified Nokia M2M module. If the HLA address is empty, the value is zero (0). Note: These special operations are needed if there is an Object Request Broker (ORB) in the AM that wants to publish mobile object references. 52/87

59 5.8 EXTENDED OPERATIONS The extended operations described in this chapter can be used to execute multiple functions with one operation message. These operations are meant to be used in a resource limited AM where full protocol implementation is not suitable CONNECT_EXT Direction: From the AM to the Nokia M2M module. Description: The AM uses this operation to create a connection to the target in one operation. While the CONNECT_EXT operation is active other operations cannot be executed until a link and a socket over the link are successfully created, or the creation attempt has failed. When the Nokia M2M module receives the CONNECT_EXT message, it checks whether there already is an open link that has the specified connection index. If the requested link already exists, the Nokia M2M module uses it. If the requested link does not exist, the Nokia M2M module opens it. Once the link is open, the Nokia M2M module creates a socket, binds it to a local port (assuming the specified target port value is not 0), and opens the socket according to the specified socket type. After that the Nokia M2M module returns a CONNECT_EXT_RESP message indicating that the socket is ready to send and receive data. If TCP protocol is used, the operations are SEND and RECEIVE. If UPD protocol is used, the operations are SEND_TO and RECEIVE. The CONNECT_EXT CONNECT_EXT_RESP sequence is illustrated in Figure 8. 53/87

60 AM NLL Nokia M2M module CONNECT_EXT (target IP, target port) Open link (USED_CONNECTION) Create socket Bind socket CONNECT_EXT_RESP(SCKT_OK, socket_id, link_id) Connect socket Figure 8. CONNECT_EXT - CONNECT_EXT_RESP sequence When the socket is not needed anymore, the AM must close it by using the CLOSE operation. When the AM receives a LINK_NOTIFICATION message from the Nokia M2M module informing that a specified link has closed, all the sockets that have been created with the CONNECT_EXT message close as well. Table 44. CONNECT_EXT operation Data type Name Description int Connection index Specifies the connection index to be used. The connection index must refer to one of the connections that have been preconfigured to the Nokia M2M module. The USED_CONNECTION index is used to open the default connection. int Socket type Stream (SCK_STREAM) or datagram (SCK_DGRAM). 54/87

61 Data type Name Description int Protocol TCP or UDP. byte Address type IPv4 or IPv6. ushort Target port The target port to be connected. byte array Target IP address 4 bytes if the addressing type is IPv4, 16 bytes if the addressing type is IPv6. ushort Source port The source port to be used. Used with datagram sockets CONNECT_EXT_RESP Direction: From the Nokia M2M module to the AM. Description: A return response from the Nokia M2M module to the CONNECT_EXT operation. Returns the status, socket ID and link ID of the requested operation. A separate link status field indicates whether the link was already open or whether it was opened as a result of the CONNECT_EXT operation. Table 45. CONNECT_EXT_RESP operation Data type Name Description int Status SCKT_OK or one of error status codes listed in SOCKET, LINK, BIND, and CONNECT operations. int Socket ID The socket ID of the opened socket. int Link status One of status codes described in the LINK_OPEN_RESP message. int Link ID The link ID of the opened link. 55/87

62 APPENDIX A: OPERATION CODES Each operation has a unique operation code. The currently specified codes are listed in the following table. Table 46. Operation codes Function RESET LINK LINK_OPEN LINK_STATUS_NOTIFICATION LINK_CLOSE SOCKET SOCKET_CLOSE BIND LISTEN ACCEPT_NOTIFICATION CONNECT SEND SENDTO SCKT_FLOW_CTRL_NOTIFICATION RECEIVE RECEIVE_NOTIFICATION GETHOSTBYNAME GET_IDENTITY CONNECT_EXT Operation code 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0A 0x0B 0x0C 0x0D 0x0E 0x0F 0x10 0x11 0x12 56/87

63 APPENDIX B: PROTOCOL CONSTANTS Some constants that are not found from the Nokia M2M module are allocated from a wider value range (0xFF - 0xFFFF). Table 47. Socket address format symbols Symbol ID Value (hexadecimal) SCKT_AF_INET 0x04 IPv4 SCKT_AF_INET6 0x06 IPv6 Description Table 48. Socket type symbols Symbol ID Value (hexadecimal) Description SCKT_SOCK_STREAM 0x01 Streaming SCKT_SOCK_DGRAM 0x02 Datagram Table 49. Socket protocol symbols Symbol ID Value (hexadecimal) SCKT_IPPROTO_TCP 0x06 TCP SCKT_IPPROTO_UDP 0x11 UDP Description Table 50. Connection ID Symbol ID Value (hexadecimal) Description USED_CONNECTION 0xFD Default connection Table 51. Link ID Symbol ID Value (hexadecimal) Description SCKT_LINK_ANY 0x00 Used to create a server socket for incoming connections SCKT_LINK_LOCAL 0xFF Used to create a local loopback k t 57/87

64 Symbol ID Value (hexadecimal) Description socket Table 52. Socket bearer type symbols Symbol ID Value (hexadecimal) Description SCKT_BEARER_CSD 0x00 CSD/HSCSD SCKT_BEARER_GPRS 0x02 GPRS/EGPRS SCKT_BEARER_SMS 0xFD SMS Table 53. Socket status symbols Symbol ID Value (hexadecimal) Description SCKT_OK 0x00 Socket created successfully SCKT_EFAULT 0x01 General error notification for all operations Standard Sockets API SCKT_EADDRINUSE 0x02 Address is already in use SCKT_EADDRNOTAVAIL 0x03 Remote address is invalid SCKT_EAFNOSUPPORT 0x04 Address family not supported SCKT_ECONNREFUSED 0x05 Connection refused SCKT_ECONNRESET 0x06 Connection reset by remote peer SCKT_EINVAL 0x07 Command contains an Invalid value SCKT_EISCONN 0x08 The given socket is already connected SCKT_EMFILE 0x09 No more sockets available SCKT_ENETDOWN 0x0A Network link is down SCKT_ENETUNREACH 0x0B Destination network tb h d 58/87

65 Symbol ID Value (hexadecimal) Description cannot be reached SCKT_ENOBUFS 0x0C Out of memory SCKT_ENOPROTOOPT 0x0D Protocol option not recognized SCKT_EOPNOTSUPP 0x0E Protocol option not supported SCKT_EPROTONOSUPPORT 0x0F Protocol not supported SCKT_EPROTOTYPE 0x10 Unsuitable protocol SCKT_ESOCKNOSUPPORT 0x11 Socket type not supported SCKT_ETIMEDOUT 0x12 Timeout SCKT_ENOTCONN 0x13 Socket not connected SCKT_ENOTSOCK 0x14 Invalid socket descriptor SCKT_EADDRINVAL 0x15 Invalid address SCKT_ELINKID 0x16 Invalid link ID SCKT_ECLOSING 0x33 TCP connection closing M2M System Protocol 2 specific values SCKT_FLOW_CONTROL_ON 0x1A Flow control on SCKT_FLOW_CONTROL_OFF 0x1B Flow control off SCKT_FLOW_CONTROL_ON_SUSP ENDED Standard Sockets DNS API 0x31 Flow control suspended SCKT_HOST_NOT_FOUND 0x20 Host not found SCKT_TRY_AGAIN 0x21 No response from authoritative DNS server SCKT_NO_RECOVERY 0x22 Unrecoverable error SCKT_NO_ADDRESS 0x23 No Internet address or name at the DNS server SCKT_SERVICE_UNAVAILABLE 0x24 Name service is not available Network Link Operations 59/87

66 Symbol ID Value (hexadecimal) Description LINK_OK 0x00 Link created successfully NO_BEARER 0xFFFE No bearer has been defined for the given connection SCKT_NETWORK_SUSPENDED 0xFFFC Network suspended SCKT_NETWORK_OPENED 0x80 Network link is opened SCKT_NETWORK_CLOSED 0x81 Network link is closed SCKT_NETWORK_DISCONNECTED 0x83 Network disconnected due to a dropped call, disconnected pipe or dropped bearer service SCKT_NETWORK_OPEN_IN_PROG RESS SCKT_NETWORK_BEARER_NOT_A VAILABLE SCKT_NETWORK_PPP_NEG_FAILE D 0x86 0x87 0x8A Network link opening in progress Selected bearer is not available PPP negotiation failed between the Nokia M2M module and wireless network SCKT_NETWORK_RESUMED 0x9D Network suspension has been cleared 60/87

67 APPENDIX C: M2M SYSTEM PROTOCOL 2 CHARACTERISTICS FOR THE NOKIA 12 GSM MODULE This chapter describes the M2M System Protocol 2 characteristics for the Nokia 12 GSM module. IPv6 The Nokia 12 GSM module does not support IPv6. If an IPv6 related message (for example SCKT_AF_INET6) is sent to the Nokia 12 GSM module, it returns the message with a suitable error status. Extension field The Nokia 12 GSM module does not support extension fields. If the Nokia 12 GSM module receives a message with extension field data, it processes other parts of the message but ignores the data in the extension field. Maximum transfer unit The MTU values used in the Nokia 12 GSM module are as follows: SEND message: 4078 bytes SEND_TO message: 4067 bytes Note: The MTU values described above are valid when the messages contain no extension fields. If the messages include extension fields, the MTU values change accordingly. Maximum receive unit The MRU value of the Nokia 12 GSM module is 4065 bytes. Number of sockets The AM can open or accept a maximum of 20 sockets via the Nokia 12 GSM module. The number of sockets, however, may also be limited by the available memory in the Nokia 12 GSM module. 61/87

68 APPENDIX D: MINIMUM IMPLEMENTATION REQUIREMENTS FOR THE M2M SYSTEM PROTOCOL 2 This chapter lists the minimum implementation requirements for the M2M System Protocol 2. This list includes messages needed for operations such as sending, receiving, communicating over a wireless link and using server sockets. If some of these operations are not needed, commands in the corresponding section can be omitted. To be able to use the M2M System Protocol 2, at least the following common commands are required: RESET and RESET_RESP are always required. They are required in protocol initialisation and to be able to handle fatal protocol error situations, such as packet loss. CONNECT_EXT and CONNECT_EXT_RESP are required to create a connection using a single message. CONNECT_EXT creates a link (if needed) and a socket, binds it (if needed) and also connects the socket. CONNECT_EXT cannot be used to create server sockets, because the created socket is always connected. SOCKET_CLOSE and SOCKET_CLOSE_RESP are required to be able to close sockets created with CONNECT_EXT. If the M2M System Protocol 2 is used over a wireless link: LINK_STATUS_NOTIFICATION and LINK_STATUS_NOTIFICATION_RESP are required to be able to handle link status notifications sent by the Nokia M2M module. If the M2M System Protocol 2 is used to communicate only in the local host domain, the Nokia M2M module does not send LINK_STATUS_NOTIFICATION messages, and thus the handling of these messages is not required in the AM. For sending data, the following commands are needed: SEND and SEND_RESP are required to send data using TCP sockets. SCKT_FLOW_CTRL_NOTIFICATION and SCKT_FLOW_CTRL_NOTIFICATION_RESP to handle flow control situations. If receiving is needed the following commands must be implemented: RECEIVE and RECEIVE_RESP are required to request receive for a given socket. 62/87

69 RECEIVE_NOTIFICATION and RECEIVE_NOTIFICATION_RESP are required to receive data. For server socket capability: SOCKET, SOCKET_RESP, BIND and BIND_RESP to create and bind a socket that can be used as a server socket. (When the CONNECT CONNECT_RESP command pair is added, these commands can be used together to replace the functionality of CONNECT_EXT, if that approach is preferred in implementation) LISTEN and LISTEN_RESP are required for an AM to be able to set the socket (created by using the commands above) into listening state, that is, to a server socket. ACCEPT_NOTIFICATION and ACCEPT_NOTIFICATION_RESP are used to accept incoming sockets from the server socket. An incoming socket can be refused only by immediately sending a SOCKET_CLOSE to the new socket. 63/87

70 APPENDIX E: AN EXAMPLE OF PARALLEL FCS CALCULATION Introduction The following algorithm describes a CRC generator which calculates the FCS in an octet-oriented parallel mode using the generator polynomial G(x) = x 16 + x 15 + x This method may shorten the time for FCS calculation and is more useful with standard DTE (PC) than a bit-oriented mode. The octet-oriented algorithm is defined by the programming language C and is intended to assist the system designer with a CRC generator implementation, but methods other than 8-bit oriented methods are also possible. The general method is to calculate the FCS in an octet mode by using a lookup table. This lookup table may be produced after device initialization or it may be stored permanently. Note: The first three IA5 control characters (SYN-DLE-STX) are not taken into account in FCS calculation, but the calculation starts from the fourth data octet (the first data octet of the header field). Lookup table production algorithm To produce the lookup table, the following two steps are required: 1. Calculate the 16-bit remainder for each bit position in an octet ( 2 0, 2 1,..., 2 7 ) through division by G(x). 2. Produce the lookup table for any octet pattern ( ) by modulo 2 sum of the 16-bit remainder of each bit position. With asynchronous character transmission, bit 1 of an octet is the first bit to be transmitted. In the DLL standard, the FCS is placed into two octets as shown in Table 54. Table 54. FCS mapping convention b8 b1 Octet Octet A 16-bit shift register used for division with G(x) is defined by shreg = x 0... x 7 x 8... x 15. This shift register will be shifted to the right. 64/87

71 The generator polynomial G(x) (excluding the highest bit x 16 ) is mapped on a 16-bit constant CRC16 in the following manner: CRC16 = x 0... x 15 = = 0xA001. The two-octet division remainder is stored in the lookup table according to the FCS mapping convention. The octets are swapped and stored as octet 1 = x 8... x 15 and octet 2 = x 0... x 7. The table entries corresponding to b8...b1=0x00...0xff are represented in Table 55. Table 55. Lookup table mtab b 4...b 1 b 8...b A B C D E F C1C0 81C C3 C C2 01C6 C C C1C5 81C CC C00C 800D 41CD 000F C1CF 81CE 400E 000A C1CA 81CB 400B 01C9 C C8 2 01D8 C D9 001B C1DB 81DA 401A 001E C1DE 81DF 401F 01DD C01D 801C 41DC C1D4 81D D7 C D6 01D2 C D C1D1 81D F0 C F C1F3 81F C1F6 81F F5 C F C C1FC 81FD 403D 01FF C03F 803E 41FE 01FA C03A 803B 41FB 0039 C1F9 81F C1E8 81E EB C02B 802A 41EA 01EE C02E 802F 41EF 002D C1ED 81EC 402C 7 01E4 C E C1E7 81E C1E2 81E E1 C E0 8 01A0 C A C1A3 81A C1A6 81A A5 C A C C1AC 81AD 406D 01AF C06F 806E 41AE 01AA C06A 806B 41AB 0069 C1A9 81A A 0078 C1B8 81B BB C07B 807A 41BA 01BE C07E 807F 41BF 007D C1BD 81BC 407C B 01B4 C B C1B7 81B C1B2 81B B1 C B0 C 0050 C C C C D 019C C05C 805D 419D 005F C19F 819E 405E 005A C19A 819B 405B 0199 C E 0188 C B C18B 818A 404A 004E C18E 818F 404F 018D C04D 804C 418C F 0044 C C C C An algorithm to produce a lookup table is shown in the function create_table, represented in Table 56. The first loop (i=0 to 8) calculates the 16-bit remainder for each bit position (step j). The result of 0x80 (2 0 in the FCS mapping convention) is stored in the field btab[0]; the result of 0x01 (2 7 in the FCS mapping convention is stored in btab[7]. 65/87

72 The second loop (i=0 to 256) calculates the final lookup table entries as the modulo 2 sum of the corresponding btab entries (step ii). For example, the table entry for the octet pattern 0x41 is calculated thus: btab[1] btab[7] = 0xC1C0 0x01F0 = 0xC030. Table 56. Function create_table CRC16 0xA001; /* CRC 16 constant */ unsigned int mtab[256]; /* modification table */ /************************************************************ Function: create_table produce the look-up table Input: *mtab pointer to modification table Output: Note: CRC16 is used ************************************************************/ void create_table(unsigned int *mtab) { unsigned int btab[8]; /* table btab */ unsigned int i,j; /* loop parameters */ unsigned int q; /* calculation register */ unsigned int shreg; /* shift-register */ unsigned int carry,bit; /* bit parameters */ /************************************************************ Calculate the table btab: ************************************************************/ carry=1; /* carry flag set to one */ shreg=0; /* shreg initialised with 0 */ for(i=0; i<8; i++) { if(carry) shreg^=crc16; btab[i]=(shreg<<8) (shreg>>8);/* swap bytes */ carry=shreg & 1; shreg >>=1; } /************************************************************ Calculate the modification table mtab: ************************************************************/ for (i=0; i<256; i++) { q=0; bit=0x80; for (j=0; j<8; j++) { if (bit & i) q^=btab[j]; bit>>=1; } *mtab++=q; } } FCS calculation algorithm The calculation of the FCS with a lookup table requires the following steps: 66/87

73 1. Initialise the FCS register (normally preset to all ones). 2. Produce an 8-bit table pointer by modulo 2 sum of the next data octet and the FCS high-order octet.(x 8... x 15 ). 3. Fetch the modification value by the pointer. 4. Add (modulo 2) the modification value high-order octet and the FCS loworder octet (x 0... x 7 ). Repeat step b to d until the last data byte is checked. 5. Produce the FCS ones complement for transmission. An algorithm for FCS calculation is shown in the function fcs_calc, presented in Table 57. Table 57. Function fcs_calc /************************************************************ Function: fcs_calc calculates the FCS sequence Input: *mtab pointer to modification table *buff pointer to character buffer len length of character string Output: fcs frame check sequence Note: fcs is initialised with all ones ************************************************************/ unsigned int fcs_calc(unsigned int *mtab, unsigned char *buff,unsigned int len) { unsigned int fcs; /* frame check sequence */ unsigned int q; /* calculation register */ } fcs=0xffff; /* fcs initialised with all ones */ while(len--) { q=*(mtab+(*buff++ ^ (fcs>>8))); fcs=((q&0xff00) ^ (fcs<<8)) (q&0x00ff); } return (fcs^0xffff); /* return the fcs ones complement */ FCS calculation example The main steps of FCS generation are shown in Table 58. The following example may help to understand this calculation method. Example: 67/87

74 There are nine data octets to be protected. The values of the data octets are 0x16, 0x10, 0x02, 0x01, 0xFF, 0x01, 0x80, 0x10, and 0x03. The result of the FCS calculation will be added after these data octets. The FCS register is initialised to 0xFFFF. a) The modulo 2 sum of data octet and the initialized FCS register value (high octet) b) The modification value fetched by pointer 0xFE is 0x8180, which comprises mtab H and mtab L. c) The modulo 2 sum of mtab H = 0x81 and the initialized FCS register value (low octet) d) Gives a new FCS value of 0x7E80. The following steps (e h) will be done in the same sequence as in the steps (a d) but using the results of the first calculation (0x7E80). i) y) the same steps are repeated z) After the last data octet calculation (0x03), the 1 s complement of FCS is calculated by the modulo 2 sum of the FCS value with 0xFFFF, which gives a result of A7F4. The 11 octets to be transmitted, data + FCS, are 0x16,0x10, 0x02, 0x01, 0xFF, 0x01, 0x80, 0x10, 0x03, 0xA7, and 0xF4. Table 58. FCS generation a) data (0x01) The fourth octet FCS H (0xFF) b) Pointer (0xFE) pointer to the modification table mtab c) mtab H (0x81) mtab L (0x80) mtab value high and low order octets FCS L (0xFF) d) FCS H (0x7E) FCS L (0x80) new FSC high and low order octets e) Data (0xFF) The fifth octet 68/87

75 FCS H (0x7E) Result of the previous FCS calculation (high octet) f) Pointer (0x81) pointer to the modification table mtab g) mtab H (0xC0) mtab L (0x60) mtab value high and low order octets FCS L (0x80) Result of the previous FCS calculation (low octet) h) FCS H (0x40) FCS L (0x60) New FCS. i) y). The same sequence is repeated to the rest of the octets (01, 80, 10, 03). z) FCS H (0x58) FCS L (0x0B) The result of calculation of the ninth octet 0xFF 0xFF FCS H (0xA7) FCS L (0xF4) The final FCS ones complement 69/87

76 APPENDIX F: SDL REPRESENTATION OF THE DATA LINK LAYER Overview This Specification and Description Language (SDL) presentation of the data link layer protocol is designed to help implementations. Certain assumptions have been made in it and certain values have been assigned to variables. This does not mean that other values may not be used. Protocol states are purely used as examples and a designer may choose to have a different number of states. If there is any discrepancy between the textual presentation and the SDL presentation, the text in the normative section 4 should have a higher priority. The following textual version is a graphical presentation of this SDL. It defines an optional procedure for an implementation of an extended link establishment timeout. For more information on the actual SDL presentation, see SDL presentation. SDL definitions This is the data_link process described in 'linear SDL' by subdivision into the following states: reset_wait: link_wait: ready: This is the default state when the power is turned on, and this state is used for connection reset. When the power is turned on, it causes the data_link process to immediately activate the 'transition' initiated by the input 'power_on'. The data_link process remains in this state until it is satisfied that its opposite number has also started link establishment. On completion of the transition, it changes state to 'link_wait'. The data_link process remains in this state until it is certain that it can communicate with its opposite number at the remote end of the M2M System Connector. Whenever it enters this state, the linkestablishment timer (T0) must be started. Whenever it leaves this state, the NLL must be informed. The data_link process resides in this state as long as it believes it is in communication with its opposite number. If it loses communication, it must inform the NLL, attempt to re-establish the link, and return to the reset_wait and link_wait processes. Whenever it enters this state, the 'credit_report_timer' (T3) must be started. When in this state, data packets may be exchanged via the M2M System Connector. When the data_link process exits this state, no timers (except the link-establishment timer) can be left running. 70/87

77 Timers The following timers exist and these timers may have a higher priority than the other messages: T0 link_establishment_timer T1 retry_timer T2 acknowledgement_timer T3 activity_timer T4 link_failure_detection_timer Inputs from the operating system When the power is turned on, the following message is input to this process: power_on Inputs from timers Expired timers input the following messages: link_establishment_timeout(t0) retry_timeout(t1) acknowledgement_timeout(t2) activity_timeout(t3) link_failure_detection_timeout(t4) Inputs from the M2M System Connector The following input messages may be received from the M2M System Connector: link_request (maximum_length, window_size, version) link_acknowledge (rx_sequence_number, rx_credit_number) link_transfer (tx_sequence_number, acknowledgement_request, network_layer_message) Inputs from the Network Link Layer The following input messages may be received from the NLL: 71/87

78 network_layer_reset network_layer_packet (network_layer_message) Note that in this case, the message passing mechanism must wrap the NLL message in an envelope labelled 'network_layer_packet'. credit_value (receive_credit) The NLL must send this message to the data link layer whenever it removes a packet from its data_link layer input buffer. Outputs to the M2M System Connector The following outputs may be sent along the M2M System Connector link: link_request (maximum_length, window_size, version) This message is sent to the M2M System Connector with its parameters set to the current values of maximum_length, window_size and version. link_acknowledge (rx_sequence_number, rx_credit_number) When this output is initiated, the data-link layer first stores the value of 'receive_credit' in the variable send_credit'. The link_acknowledge message is then sent to the M2M System Connector with parameter 'rx_sequence_number' given the value of 'receive_state' and parameter 'rx_credit_number' given the value of 'receive_credit'. link_transfer (tx_sequence_number,acknowledgement_request, network_layer_message) When this message is sent to the M2M System Connector, its parameters are set to 'send_state' and 'LT_acknowledge_request' respectively, and its data area is filled with a NLL message from the queue of messages waiting to be transmitted. The correct message is identified by selecting the one whose stored_packet_number is equal to the value of the variable 'send_state'. Outputs to the Network Link Layer The following outputs may be sent to the NLL: link_ready link_failure packet_accepted packet_rejected 72/87

79 network_layer_packet (network_layer_message) Note that in this case, the message-passing mechanism must present the packet to the NLL as a variable message whose type depends upon the first octet of the packet's contents. Constants The following constants are defined: N2 Maximum number of retransmissions N3 Maximum number of inactivity timeouts T0 Link establishment time T1 Retry time T2 Acknowledgement time T3 Activity time T4 link_failure_detection_time tx_messages_buffer o A buffer >= maximum possible value ( k * 16 * (N1+1)). tx_message_pointer o A pointer to the next message to be transmitted unit_maximum_length o The maximum message length this unit can accommodate. unit_maximum_window_size o The maximum window size this unit can accommodate. unit_version o The highest DLL version number this unit knows. CV Current Version Variables The following variables are defined for interfacing between the TASKs and IFs: AR LT_acknowledge_request 73/87

80 N1 maximum_length (number of octets is 16 * (N1+1)) C1 retransmission_count k window_size N(k) rx_credit_number N(R) rx_sequence_number R(k) receive_credit S(k) send_credit SN(R) stored_acknowledged_rx_sequence_number SR(k) stored_receive_credit V(S) send_state_variable V(R) receive_state_variable TASKs The following TASKs are defined adjust_link_parameters - Sets values of variables maximum_length, window_size and current_version to the minima of unit_maximum_length, unit_maximum_window_size, and unit_version, and the values of the corresponding parameters received in the most recently received 'link_request' message. decrement_retransmission_counter(c1) - Decrements the variable 'retransmission_count' (C1). decrement_send_credit - Decrements the variable 'send_credit' (S(k)). delete_acknowledged_packets - Removes acknowledged messages from the queue of network layer messages awaiting transmission by deleting all messages with 'stored_packet_number' less than the value of 'rx_sequence_number' (N(R)) in the last received link_acknowledgement message. increment_send_state_variable 74/87

81 - Increments the variable 'send_state_variable' (V(S)). initialise_variables - Sets the following: send_state = 1 receive_state = 1 receive_credit = k send_credit = 0 stored_acknowledged_rx_sequence_number = 1 clears data link layer message buffers clears M2M system connector buffers retransmission_count = N2 initialise_system_connector - This task sets the M2M System Connector ready to operate at the preselected speed (see Table 2 for supported speeds), with 8 bits, no parity, 1 start bit and 1 stop bit. maximise_link_parameters - Sets the values of variables 'maximum_length' (N1), 'window_size' (k) and 'current_version' (VERSION) to the maximum permissible for this unit, (that is, unit_maximum_length, unit_maximum_window_size, and unit_version). record_send_credit - Stores r the 'send_credit', S(k) as: S(k) =N(k) - (V(s)-N(r)) = rx_credit_number - (send_state_variable - rx_sequence_number). rewind_packet_number - Sets the 'send_state', V(S), to the value of the rx_sequence_number parameter (N(R)) of the last received link_acknowledgement message, and sets the tx_message_pointer to the corresponding message in the tx_messages_buffer, so that it is the next message to be transmitted. set_retransmission_counter - Sets the variable 'retransmission_count' (C1) to its maximum value, N2. 75/87

82 store_acknowledged_rx_sequence_number - Stored the latest received rx_sequence_number as stored_acknowledged_rx_sequence_number. store_packet - Stores the most recent packet from the NLL, and marks it with a 'stored_packet_number' equal to the current value of the variable 'transmit_buffer_top' and increments the variable 'transmit_buffer_top'. store_receive_credit - Stores the current 'receive_credit' (R(k)) as 'stored_receive_credit' SR(k). update_receive_credit - Calculates the last received 'credit_value' message from the NLL as the new 'receive_credit' (R(k)). Conditional statements (IFs) The following tests are defined: acknowledgement_outside_window - Returns 'true' if the rx_sequence_number (N(R)) of the last received 'link_acknowledgement' message is outside the range of stored_acknowledged_rx_sequence_number SN(R) to send_state_variable V(S). all_transmitted_packets_acknowledged - Returns 'true' if the 'rx_sequence_number' (N(R)) parameter of the last received 'link_acknowledgement' message is one greater than the 'tx_sequence_number' parameter of the last transmitted 'link_transfer' message (equal to current V(S)). immediate_reply_requested - Returns 'true' if the 'acknowledgement_request' (AR) field of the most recently received link_transfer message is set to '1'. packet_out_of_sequence - Returns 'true' if the sequence_number (N(S)) of the last received link transfer message is not equal to the 'receive_state_variable' (V(R)). 76/87

83 packet_outside_window - Returns true if the tx_sequence_number of the last received link_transfer message is outside the range of values given by the expression [(rx_sequence_number - stored receive_credit) to (rx_sequence_number-1 + rx_credit_number)], these variables being the values of parameters in the last transmitted link_acknowledge messages. receive_credit_available - Returns 'true' if there is enough buffer space available in the NLL to pass the network_layer_message content of the last received link_transfer message to the NLL. received_parameters_acceptable - Returns 'true' if the parameters in the last received 'link_request' message (maximum_length, window_size, version) are less than or equal to the maximum permissible values for this unit. repeated_link_acknowledge - Returns 'true' if the rx_sequence_number of the last received 'link_acknowledge' message is equal to the rx_sequence_number of the penultimate received 'link_acknowledge' message, and is not equal to 'send_state'. retransmission_count_zero - Returns 'true' if the variable 'retransmission_count' (C1) is zero. send_credit_available - Returns 'true' if send_credit is greater than zero. Note: Unless stated otherwise, INPUTS and OUTPUTS go via the M2M System Connector to the co-operating data_link process. SDL presentation PROCESS data_link STATE reset_wait INPUT network_layer_reset /* -- from the network layer -- */ /* or */ INPUT power_on /* -- from operating system -- */ TASK initialise_system_connector 77/87