Nokia M2M Platform M2M System Protocol 2 Socket
Contents
1. sp2_send sp2_sendto status SEND SENDTO gt Start sending data SEND_RESP 17 46 Figure 8 Sending data to a socket The parameters of the sp2_send function call are described in Table 13 Table 13 The sp2_send function call parameters Parameter Description Socket ID A handle to a socket to which data is written Buffer Data to be sent Data length The length of the data in bytes Flags Send flags The parameters of the sp2_sendto function call are described in Table 14 Table 14 The sp2_sendto function call parameters Parameter Description Socket ID A handle to the socket to which data is written Buffer Data to be sent Data length The length of the data in bytes Flags Send flags Address The address of the socket to which data is written Address length The length of the socket address in bytes The return values of both the sp2_send and sp2_sendto function calls are described in Table 15 Table 15 The sp2_send and sp2_sendto function call return values Return value Description Bytes written Number of bytes written successfully SP2_SOCKET_ERROR Failure to write data An example of sending data to a socket DWORD socketID the handle to the socket to which data is written BYTE buff DATA_LENGTH buffer to store data to be written DWORD nbytes DATA LENGTH2. Return value Description SP2_OK Link was stopped successfully SP2_ERROR Failure to stop a link An example of stopping a M2M System Protocol 2 link DWORD status a return value from the function status sp2_stop if status SP2_OK WIRELESS LINK CONTROL API The Wireless Link Control API makes it possible to open and close a pre configured connection of the Nokia M2M module Since the configuration cannot be changed via the Wireless Link Control API the connection configuration must be done either locally using the Configurator software for the Nokia M2M module or remotely over the air via the Nokia M2M Gateway Opening a wireless link sp2_link_open The sp2_1ink_open function is used to establish a wireless link over a GSM network via the Nokia M2M module The sp2_1ink_open function call is illustrated in Figure 14 25 46 Application software M2M System Protocol 2 Nokia M2M module software sp2_link_open A LINK_OPEN LINK_OPEN_RESP T lt err_status Open the link lt LINK_NOTIFICATION LINK_NOTIFICATION_RESP status In case an error occurs the function returns with an error status Figure 14 Opening a wireless link The parameters of the sp2_1ink_open function call are described in Table 25 The return values from the sp2_1ink_open function call are described in Table 26 T
3. HelloWorld Client M2M System Protocol 2 HelloWorld Server Start M2M System Protocol 2 s M2M System Protocol 2 started event Start HelloWorld Server Create a server socket Bind the socket Listen to the socket Wait a socket connection Create a socket 5 Connect the socket x LA client socket accepted __ 5 y to receive data Send SAY PF O S Received SAY L __ __ __ Try to receive data Send HELLO WORLD Display the text HELLO WORLD on the screen Close the client socket Close the server socket Close the socket 5 Stop M2M System Protocol 2 5 LM2M System Protocol 2 stopped event __ Figure 18 Overview of the Hello World application 6 2 1 Configuring and executing the Hello World application The Hello World application includes both the client and server implementation As both the client and server of the Hello World application use the M2M System Protocol 2 sockets the socket peers are likely to be Nokia M2M modules Thus the wireless connection between the two Nokia M2M modules has to be configured so that the client can establish a connection to the server 32 46 Note An example configuration for the Nokia 12 GSM module is presented in Appendix Nokia 12 GSM module configuration for the Hello World application 6 2 2 When executing the Hello World application th
4. Network utility functions The M2M System Protocol 2 also provides some utility functions that are typically used when programming sockets The utility functions are described below Convert a 32 bit value from host byte order to network byte order DWORD sp2_htonl DWORD hostlong Convert a 16 bit value from host byte order to network byte order WORD sp2_htons WORD hostshort Convert a 32 bit value from network byte order to host byte order DWORD sp2_ntohl DWORD netlong Convert a 16 bit value from network byte order to host byte order WORD sp2_ntohs WORD netshort Convert an IPv4 address from a dotted decimal string to 32 bit network byte ordered value DWORD sp2_inet_addr const char addr Convert a 32 bit network byte ordered IPv4 address to dotted decimal string char sp2_inet_ntoa DWORD naddr M2M SYSTEM PROTOCOL 2 CONTROL API The M2M System Protocol 2 Control API makes it possible to configure open and close of a link between the AM and Nokia M2M module Starting the M2M System Protocol 2 sp2_start The sp2_start function is used to establish an M2M System Protocol 2 link between the AM and Nokia M2M module 22 46 Note The sp2_start function must be executed and the sp2_hLinkReadyEvent must be received before any other M2M System Protocol 2 API call can be made The sp2_start function configures the DLL according to the parameters give
5. LENS CIE Server should be ready before doing client s job if HelloWorldClient cleanExit 60 ERROR HelloWorldClient failed else if HelloWorldServer cleanExit 60 ERROR HelloWorldServer failed Give some time for the system to send messages Sleep 10 1000 Stop the M2M System Protocol 2 ENS Stop cleanExit 10 ERROR Cannot stop M2M System Protocol 2 The hStopEvent indicates that the M2M System Protocol 2 is stopped if system_event_wait sp2_hStopEvent 30 1000 SYSTEM OK cleanExit 20 ERROR M2M System Protocol 2 was not stopped Close all handles before exiting if CloseHandle sp2_hLinkReadyEvent CloseHandle sp2_hStopEvent cleanExit 30 ERROR Cannot close all handles cleanExit 0 Hello World successful The functionality of the Hello World client static BOOL HelloWorldClient void DWORD socket A client socket handle sp2_sockaddr_in socketAddress The address of the socket BOOL success FALSE Indicates Hello World client s success failure DWORD linkID A wireless link handle DWORD connectionID SP2_DEFAULT_CONNECTION Please note that wireless link is not needed for local sockets if linkID sp2_link_open connectionID SP2_LINK_ERROR printf sp2_link_open failed n return FALSE Create an M2M System Protocol 2 socket 35 46 socket sp2_socket SP2_AF_INET
6. Socket ID A handle to a socket which is listened to Address The address of the incoming socket Address length The length of the socket address in bytes Table 10 The sp2_accept function call return values 15 46 Return value Description Socket ID A handle to an incoming socket SP2_SOCKET_ERROR Acceptance failure An example of accepting a socket DWORD socketID a handle to the socket DWORD acceptedSocketID a handle to an incoming socket struct sp2_sockaddr_in addr incoming socket address structure DWORD addrlen incoming socket address length acceptedSocketID sp2_accept socketID sp2_sockaddr amp addr amp addrlen if acceptedSocketID SP2_SOCKET_ERROR 5 1 5 Connecting a socket sp2_connect The sp2_connect function connects a previously created M2M System Protocol 2 socket to another socket The function call is illustrated in Figure 7 Application software M2M System Protocol 2 Nokia M2M module software sp2_connect SOCKET Create a socket SOCKET_RESP err_status K CONNECT Connect the socket to a peer socket l status CONNECT_RESP kK 4 In case an error occurs the function returns with an error status Figure 7 Connecting a socket The parameters and return values of the sp2_connect function call are described in Table 11 an
7. System Protocol 2 Control API and Wireless Link Control API This chapter describes the APIs and lists the related methods parameters and return values In addition the chapter provides message sequence diagrams which illustrate message exchange caused by API calls between the AM and Nokia M2M module For more detailed description of the messages refer to the Nokia M2M Platform M2M System Protocol 2 Specification Note The M2M System Protocol 2 must be started before making any other M2M System Protocol 2 API calls For more information on how to start the M2M System Protocol 2 see Chapter 5 2 1 5 1 SOCKET API The Socket API provides a standard socket interface It supports client and server sockets and UDP TCP protocols 5 1 1 Creating a socket sp2_ socket The sp2_socket function creates a handle to a socket on the AM side of the M2M System Protocol 2 The function call is illustrated in Figure 3 Application software M2M System Protocol 2 Nokia M2M module software sp2_socket status T Create a socket l Figure 3 Creating a socket The parameters and return values of the sp2_socket function call are described in Table 3 and Table 4 Table 3 The sp2_socket function call parameters Parameter Description Domain IPv4 11 46 Parameter Description Type Stream or datagram Protocol TCP or UDP
8. Table 4 The sp2_socket function call return values Return value Description Socket ID A handle to the created socket SP2_SOCKET_ERROR Socket allocation failed An example of creating a socket DWORD socket a handle to the socket to be created BYTE addrFormat SP2_AF_INET addressing scheme is IPv4 BYTE type SP2_SOCK_STREAM TCP stream socket BYTE protocol SP2_IPPROTO_TCP TCP IP protocol is used socket sp2_socket addrFormat type protocol if socket SP2_SOCKET_ERROR 5 1 2 Binding a socket sp2_bind The sp2_bind function binds a previously created M2M System Protocol 2 socket to a port The fu nction call is illustrated in Figure 4 Application software M2M System Protocol 2 Nokia M2M module software sp2_bind gt Bind the socket status K Figure 4 Binding a socket The parameters and return values of the sp2_bind function call are described in Table 5 and Table 6 Table 5 The sp2_bind function call parameters Parameter Description Socket ID A handle to a socket to be bound 12 46 5 1 3 Parameter Description Address The address of the socket to be bound Address length The length of the socket address in bytes Table 6 The sp2_bind function call return values Return value Description SP2_ SOCKET OK Socket was
9. 4 46 The wireless connectivity makes it possible to connect the Nokia M2M module to a remote peer over a GSM network Thus application software can be connected to sockets located on remote machines For more information on the wireless connectivity solutions available via the Nokia M2M Platform see the Nokia M2M Platform Software Developer s Guide 5 46 THE M2M SYSTEM PROTOCOL 2 SOFTWARE DESCRIPTION 3 1 3 2 3 3 The M2M System Protocol 2 is based on the Open Systems Interconnection OSI Reference Model It is a set of layers organized in a hierarchical structure where each layer uses the layer below and provides services for the layer above When data is sent from application software to a network it flows downward the stack layer by layer until it has passed through the whole stack When the data reaches the bottom layer it is passed to a network The data received from the network flows the stack in an opposite direction The software structure of the M2M System Protocol 2 is illustrated in Figure 2 Application software Socket interface Network Link Layer Operating Operating system system Data Link Layer wrapper services Serial communication wrapper Serial communication services Figure 2 M2M System Protocol 2 software structure SOCKET INTERFACE The socket interface is on the top level of the M2M System Protocol 2 It provides all the services that application software uses for socket comm
10. Protocol 2 in Win32 See the M2M System Protocol 2 Integrator s Manual for more information about this software Usage HelloWorld exe client server lt com port gt Expected output Hello World successful or an error message include lt stdio h gt The M2M System Protocol 2 Socket interface include sp2_socket h Size of buffer that holds text messages SAY and HELLO WORLD define messageBufferLen 80 static const WORD TcpPortThatServerIsListening 0x5555 33 46 iif sta sta a PSS ar SS ta it s s s iif sta Hi voi Client functionality tic BOOL HelloWorldClient void Server functionality tic BOOL HelloWorldServer void The function for writing a 0 char terminated text string to a socket tic BOOL sendMessage DWORD socket const char msg The function for reading a 0 char terminated string from a socket tic BOOL receiveMessage DWORD socket char messageBuffer int size Cleanup and exit Hello World just a convenience function tic void cleanExit int statusId char statusName This source file has both server and client functionality The first command line argument tells which role is chosen tic BOOL isClient Main entry of the Hello World application ol Wastin Gone eeen Gien Arc Serial port parameters BYTE COMPort LONG COMPortSpeed 115200 Hote ance cleanExit 0 Usage h
11. SP2_SOCK_ STREAM SP2_IPPROTO_TCP if socket SP2_SOCKET_ERROR socketAddress sin_ family SP2_AF_INET socketAddress sin port sp2_htons TcpPortThatServerlsListening socketAddress sin_addr sp2_inet_addr 10 0 0 1 if sp2_connect socket sp2_sockaddr amp socketAddress sizeof socketAddress SP2_SOCKET_ERROR const char sayString SAY printf Client send message s n sayString if sendMessage socket sayString char messageBuffer messageBufferLen if receiveMessage socket messageBuffer messageBufferLen printf Client got message s n messageBuffer if strcmp messageBuffer HELLO WORLD 0 success TRUE else printf ERROR Client receiveMessage n else peinte TERROR Client sp2_send n else Prints TERROR Client sp2mconnect yn if sp2_close socket SP2_SOCKET_ERROR printf ERROR Client sp2_close n else printf TERROR Client sp2_socket n Remember to close the wireless link if opened earlier if sp2_link_close linkID SP2_LINK_OK Prints UERRORs Client spe imke losen return success The functionality of the Hello World server static BOOL HelloWorldServer void DWORD serverSocket server socket handle DWORD socket SP2_SOCKET_ERROR A data socket handle from the client sp2_sockaddr_in socketAddress Socket address structure DWORD addrLen Socke
12. Server sp2_listen n return FALSE else printf ERROR Server sp2_bind n return FALSE else printf ERROR Server sp2_socket n return FALSE if sp2_close serverSocket SP2_SOCKET_ERROR printf ERROR Server socket sp2_close n return FALSE 37 46 return TRUE The function for writing a 0 char terminated text string to a socket BOOL sendMessage DWORD socket const char msg int bytesSent 0 int size strlen msg 1 while bytesSent size Send data to the M2M System Protocol 2 Hello World messages are very short and thus probably sent in one request However the number of bytes written is checked and sending is looped until all the data has been sent int n sp2_send socket msgtbytesSent size bytesSent 0x00 if n SP2_SOCKET_ERROR printf ERROR sp2_send n return FALSE bytesSent n Yield Just to let other threads run return TRUE The function for reading a 0 char terminated string from a socket BOOL receiveMessage DWORD socket char messageBuffer int size int bytesReceived 0 BOOL isMessageReceived FALSE Read until the 0 char is received while isMessageReceived Receive data from the M2M System Protocol 2 Hello World messages are very short and thus probably received in one request However the number of bytes read is checked and receiving is looped unt
13. bound successfully SP2_SOCKET_ERROR Socket binding failed An example of binding a socket DWORD socketID a handle to the socket DWORD status a return value from the function struct sp2_sockaddr_in addr socket address structure for IPv4 addr sin_family SP2_AF_INET addressing scheme is IPv4 addr sin_port sp2_htons 1234 port to which the socket is to be bound addr sin_addr sp2_inet_addr 127 0 0 1 a socket address Listening to a socket sp2_listen Status sp2_bind socketID sp2_sockaddr amp addr sizeof addr i if status SP2_SOCKET_OK The sp2_listen function creates and binds a socket to the Nokia M2M module and initiates the listening of the incoming socket connection requests The function call is illustrated in Figure 5 13 46 Application software sp2_listen M2M System Protocol 2 Nokia M2M module software err_status SOCKET j Create a socket SOCKET_RESP K BIND gt Bind the socket BIND_RESP err_status K LISTEN gt Start listening to the socket LISTEN_RESP status K Waiting for incoming connection requests In case an error occurs the function returns with an error status Figure 5 Listening to a socket The parameters and return values of the sp2_listen function call are described in Table 7 an
14. is composed of the socket interface protocol stack NLL DLL and platform wrappers Table 1 lists the header and source files of the M2M System Protocol 2 software Table 1 The M2M System Protocol 2 implementation files Module Header files Source files Socket interface sp2_control_api h sp2_control_api c sp2_socket_api h sp2_socket_api c sp2_link_api h sp2_link_api c sp2_socket h Protocol stack sp2_nill h sp2_nil c sp2_dll h sp2_dll c sp2_rs h sp2_rs c sp2_port_socket h sp2_port_socket c Platform wrappers sp2_system_common h sp2_system_common_win32 c sp2_dbg_wrap h sp2_dbg_wrap_win32 c sp2_port h sp2_port_os_win32 c sp2_wait h sp2_port_hw_win32 c sp2_types h Application software uses the M2M System Protocol 2 functions via the socket interface An application that uses the M2M System Protocol 2 functionality must include the header file sp2_socket h The protocol stack provides the core functionality of the M2M System Protocol 2 It is recommended that application software is designed not to use the protocol stack directly The platform wrappers contain the platform specific implementation of the operating system and serial communication services for the M2M System Protocol 2 The platform wrappers must be configured separately for each AM platform 8 46 Note The M2M System Protocol 2 file names and external identifiers except system wrappers are prefixed with sp2 to avoi
15. value Description SP2_OK M2M System Protocol 2 was started successfully SP2_ERROR Failure to start the M2M System Protocol 2 An example of starting a M2M System Protocol 2 link BYTE nl 255 maximum data field length n 16 N1 1 BYTE n3 10 activity timer is 10s BYTE t3 5 system protocol parameter T3 BYTE port 1 use COM port 1 DWORD baudrate 115200 serial speed is 115200 bps DWORD status a return value from the function Status Sp stact nl no ts port paud rate if status SP2_OK 5 2 2 Stopping the M2M System Protocol 2 sp2 _stop The sp2_stop function is used to stop an M2M System Protocol 2 link between the AM and Nokia M2M module The function call is described in Figure 13 Note After this function is called and the st op event is received the M2M System Protocol 2 resources are freed and the protocol must be restarted before issuing any further API requests 24 46 Application software M2M System Protocol 2 Nokia M2M module software 5 3 5 3 1 sp2_stop RESET Reset the NLL RESET_RESP Stop all active operations status and release all resources Figure 13 Stopping the M2M System Protocol 2 The sp2_stop function call does not have any parameters The return values are described in Table 24 Table 24 The sp2_stop function call return values
16. 2 Control API 3 Wait for an incoming socket request via the Socket API 30 46 4 Communicate with the client via the Socket API 5 Close the serial link to the Nokia M2M module via the M2M System Protocol 2 Control API A typical server socket message sequence is illustrated in Figure 17 Socket server M2M System Protocol 2 Start M2M System Protocol 2 Create a server socket Bind the server socket Listen to the server socket Accept a client socket A client socket accepted Data sending and receiving Close the client socket Close the server socket J Stop M2M System Protocol 2 Figure 17 A typical server socket message sequence D Note In case the serial link between the AM and Nokia M2M module is re established after being broken the M2M System Protocol 2 will reset the protocol all pending operations are interrupted and all sockets are closed 6 2 APPLICATION SOFTWARE EXAMPLE In this chapter the Hello world application uses the M2M System Protocol 2 client and server sockets as described in Chapter 6 1 Figure 18 shows an overview of the Hello World application in which the M2M System Protocol 2 socket interface is used to send a text string say from the client to the server and a text string HELLO worzo back from the server to the client 31 46
17. NOKIA M2M PLATFORM M2M SYSTEM PROTOCOL 2 SOCKET INTERFACE USER MANUAL NOKIA erved Issue 1 0 9312023 Copyright 2004 Nokia All rights res Contents ACRONYMS AND TERMS 222 an ON dei 1 DEFINITIONS eee a a ne da ea ea D ne Te 2 1 ABOUT THIS DOCUMENTS de en no aaeei ed 3 2 INTRODUCTION sissa a E E E 4 3 THE M2M SYSTEM PROTOCOL 2 SOFTWARE DESCRIPTION 6 3 1 SOCKETINTERFACE re annales 6 3 2 NETWORK LINK LAY BR sc ccscscssxcssswenssncaes scnasscenuscecesceectebsatededsasesseccantecetsscenetcdunatcnenads 6 3 3 DATA ONK LAYER eee ere nd dou 6 3 4 PLATFORM WRAPPERS sccescccstcsciteessnccssncessbeza en stectntaaiessseveadsaedesstdeasicdeas nade aaencedncs 7 4 INTEGRATING THE M2M SYSTEM PROTOCOL 2 WITH APPLICATION SOFTWARE 8 4 1 SOFTWARE IMPLEMENTA TION nent Renan 8 42 BUILDING THE SOFTWARE ae er ut tient 9 4 5 PORTING THE SOFTWARE aan nn nada 9 5 THE M2M SYSTEM PROTOCOL 2 SOCKET INTERFACE 11 5 1 IG RET API SR ee a eae Sere eee 11 5 1 1 Creating a socket sp2_socket sssssseesserrrerrsnresrenressrtrnnnrtnnnresrennnernnnn ennnen 11 5 1 2 Binding a socket SOs Din 12 5 1 3 Listening to a socket Sp listen mentale 13 5 1 4 Accepting a socket SPS ACCOM esses ca ncesenreigmasrsccesdeseraccearznscecretadawesbaatnudnieemeees 15 5 1 5 Connecting a socket sp2_connect siennes 16 5 1 6 Sending data to a socket sp2_send sp2_sendto ee eeeeeeeeeeeteeeeeeeeeeeeeeeeee 17 5 1 7 Receiving data from a socket sp2_
18. Point to Point Protocol PPP must be configured for the server 1 Select Bearer Selection from the M2M System Mode menu 2 Define the incoming CHAP username and password for example ntn211 ntn211 An example configuration is shown in Figure 19 M2M Bearer Selection a xj General Connection 1 Connection 2 Connection 3 Connection 4 Service connection Data call authentication JV Incoming CHAP authentication J GPRS always online Incoming CHAP username rinan Default connection Connection 1 Me Incoming CHAP password rnant HLA name I CSD Number authentication HLA port jo Read parameters Write parameters Figure 19 The Hello World server configuration for client authentication The connection of the server must be configured so that the server is ready to accept incoming requests from the Hello World client In this example the client will be configured so that it makes a TCP CSD call and that is why the wireless bearer of the server is configured to use TCP CSD 3 Select Connection 1 from the M2M Bearer Selection dialog 41 46 4 Choose TCP CSD as the wireless bearer An example configuration is shown in Figure 20 M2M Bearer Selection i xj General Connection 1 Connection 2 Connection 3 Connection 4 Service connection Wireless bearer tereso Destination address ps WTP port fo Gateway number fz Gateway IP address 0 0 0 0 Data call bit ra
19. able 25 The sp2_link_open function call parameters Parameter Description Connection ID The Nokia M2M module connection ID to be checked and opened Table 26 The sp2_link_open function call return values Return value Description Link ID Handle to an opened link SP2_LINK_ERROR Failure to open a link An example of opening a wireless link DWORD connectionID SP2_DEFAULT_CONNECTION preconfigured connection ID DWORD linkID a handle to the link that was opened linkID sp2_link_open connectionID if linkID SP2_LINK_ERROR 26 46 5 3 2 Closing a wireless link sp2_link_ close The sp2_1ink_close function is used to close a wireless link over a GSM network via the Nokia M2M module The function call is depicted in Figure 15 D Note All remote sockets must be closed before closing the wireless link Application software M2M System Protocol 2 Nokia M2M module software sp2_link_close LINK_CLOSE LINK_CLOSE_RESP x K err_status status Close the link LINK_NOTIFICATION EINE NOTIEIATION MERRI status In case an error occurs the function returns with an error status Note If the link is already closed the sp2_link_close call will return immediately and LINK_NOTIFICATION is not used Figure 15 Closing a wireless link The parameters and return value
20. ayer OS Operating System OSI Open Systems Interconnection Platform Operating system and communication services PPP Point to Point Protocol 1 46 DEFINITIONS Term Description Socket API M2M System Protocol 2 API for socket operations M2M System M2M System Protocol 2 API for serial link control Protocol 2 Control API Wireless Link Control API M2M System Protocol 2 API for GSM link control Software wrapper Used between software elements to isolate platform specific features 2 46 ABOUT THIS DOCUMENT This document describes from application software point of view how to integrate and use the M2M System Protocol 2 In addition to providing an overview of the M2M System Protocol 2 software the document includes instructions on how to integrate the M2M System Protocol 2 with application software and how to use the APIs of the M2M System Protocol 2 socket interface The document also includes an example of the M2M System Protocol 2 socket usage 3 46 INTRODUCTION The M2M System Protocol 2 software provides a socket programming interface for application software The socket interface may be used e locally between Application Module AM applications e to connect an AM application to a Java IMlet running on the Nokia M2M module e to connect an AM application to machines on the Internet or intranet via wireless connectivity over the GSM network The socket inte
21. d Table 12 Table 11 The sp2_connect function call parameters 16 46 Parameter Description Socket ID A handle to a socket to be connected Address pointer The address of a socket to which the existing socket is connected Address length The length of the socket address in bytes Table 12 The sp2_connect function call return values Return value Description SP2_SOCKET_OK Socket was connected successfully SP2_SOCKET_ERROR Connection failure An example of connecting a socket adds Sin port addr sin_addr DWORD socketID a handle to the socket DWORD status a return value from the function struct sp2_sockaddr_in addr the address of the socket to be connected addr sin_family SP2_AF_INET addressing scheme is IPv4 sp2_ sp2 htons 1234 port to which socket is to be connected imet_adde 1l27 0 0 1 y a socket address status sp2_connect socketID sp2_sockaddr amp addr sizeof addr if status SP2_SOCKET_OK 5 1 6 Sending data to a socket Sp2_send sp2_sendto The sp2_send and sp2_sendto functions write data to a previously connected M2M System Protocol 2 socket The sp2_send function is used with TCP sockets and the sp2_sendto function is used with UDP sockets Both function calls are illustrated in Figure 8 Application software M2M System Protocol 2 Nokia M2M module software
22. d Table 8 Table 7 The sp2_listen function call parameters Parameter Description Socket ID A handle to a socket to be listened Queue length Connection queue length 0 5 Table 8 The sp2_listen function call return values Return value Description SP2_SOCKET_OK Socket was connected successfully 14 46 Return value Description SP2 SOCKET ERROR Connection failure An example of listening to a socket DWORD socketID a handle to the socket DWORD status a return value from the function DWORD queueLen 1 queue length is 1 status sp2_listen socketID queueLen if status SP2_SOCKET_OK 5 1 4 Accepting a socket sp2_accept The sp2_accept function accepts an incoming socket connection The function will block until an ACCEPT NOTIFICATION is received from the Nokia M2M module The function call is illustrated in Figure 6 Application software M2M System Protocol 2 Nokia M2M module software gt Listening to incoming Wait for an accept connection requests sp2_accept notification ACCEPT_NOTIFICATION ACCEPT_NOTIFICATION_RESP mw status Figure 6 Accepting a socket The parameters and return values of the sp2_accept function call are described in Table 9 and Table 10 Table 9 The sp2_accept function call parameters Parameter Description
23. d name conflicts 4 2 BUILDING THE SOFTWARE This chapter provides a summary of how the M2M System Protocol 2 is built The instructions are written with the assumption that the reader is already familiar with application software building process in general The M2M System Protocol 2 software building process includes the following steps 1 Select platform wrapper source files for the M2M System Protocol 2 It is up to the application software developer to implement the AM platform wrappers if they are not available For more information on porting the M2M System Protocol 2 see Chapter 4 3 2 Compile all the M2M System Protocol 2 source files Compile the selected platform wrappers and all the socket interface protocol stack source files listed in Table 1 The socket interface and protocol stack source files should compile without modifications 3 Link the compiled files to application software Once the M2M System Protocol source files are compiled and optionally linked as a library they are linked with application software to produce the final binary image Tip Chapter 6 2 2 includes a sample makefile that can be used to get started with building the M2M System Protocol 2 software 4 3 PORTING THE SOFTWARE As the M2M System Protocol 2 software is integrated with application software the AM itself must have enough resources for both the M2M System Protocol 2 and application software As an examp
24. e configuration is shown in Figure 22 43 46 M2M Bearer Selection 4 ie Ea xj General Connection 1 Connection 2 Connection 3 Connection 4 Service connection m Data call authentication Incoming CHAP authentication GPRS always online Incoming CHAP username Default connection Connection 1 z Incoming CHAP password HLA name J CSD Number authentication HLA port jo Read parameters Write parameters Figure 22 The Hello World client default connection configuration A wireless connection from the client to the server has to be configured for the client The outgoing CHAP configuration of the client must match with the incoming CHAP configuration of the server in order for the server to make a client authentication In addition the phone number of the server is defined in the Gateway number field because the client calls the Gateway number to establish a data connection to the server 3 Select Connection 1 from the M2M Bearer Selection dialog Choose TCP CSD as the wireless bearer 5 Define the outgoing CHAP username and password for example ntn211 ntn211 6 Define the phone number of the server for example 123xxxxx A wireless connection configuration example for the client is shown in Figure 23 44 46 M2M Bearer Selection gi xj General Connection 1 Connection 2 Connection 3 Connection 4 Service connection Wireless bearer rcpcso Destina
25. e server must be initialized first it must be ready to accept incoming socket connections from the client The Hello World application can be executed for example from the command prompt Use the following parameters to execute the Hello worla Server gt HelloWorld exe server lt com port gt Use the following parameters to execute the Hello wor1a Client gt HelloWorld exe client lt com port gt When the Hello world application is executed without errors the client will display the text Hello World successful on the screen If an error occurs the client will display an error message with a failure explanation The Hello World implementation In the Hello woria implementation the M2M System Protocol 2 serial link is initialized first When the client receives a link ready indication it tries to establish a connection to the server that is listening to incoming sockets After the server has accepted the connection request the client will write the text string say to the socket The server reads the text from its socket and answers with a text string HELLO wortp Finally the client receives the server s greeting through its socket and displays the text on the screen Listing 1 shows the source code of the Hello world application Listing 1 Hello World an M2M System Protocol 2 example Hello World application HelloWorld c This is an example of how to use the M2M System
26. elloworld client server com port gt Iie trou ere alien 0 isClient TRUE else isClient FALSE i e isServer COMPort BYTE atoi argv 2 if isClient printf HelloWorld Client at COM port d r n COMPort else printf HelloWorld Server at COM port d r n COMPort At first create the M2M System Protocol 2 hLinkReadyEvent the hLinkReadyEvent is used by the M2M System Protocol 2 to indicate when the link between the AM and Nokia M2M module is ready if system_event_create amp sp2_hLinkReadyEvent sp2_hLinkReadyEvent cleanExit 10 ERROR Cannot create hLinkReadyEvent The hStopEvent is used by the M2M System Protocol 2 to indicate when the link between the AM and Nokia M2M module is stopped if system_event_create amp sp2_hStopEvent sp2_hStopEvent cleanExit 20 ERROR Cannot create hStopEvent Start the M2M System Protocol 2 if sp2_start 255 10 5 COMPort COMPortSpeed cleanExit 30 ERROR Cannot start M2M System Protocol 2 Wait until the M2M System Protocol 2 has started the timeout is 3 seconds if system_event_wait sp2_hLinkReadyEvent 3 1000 SYSTEM_OK 34 46 cleanExit 40 ERROR hLinkReadyEvent not OK When a link is ready the protocol state must be reset if sp2_reset cleanExit 50 ERROR Cannot reset the M2M System Protocol 2 Select the role client or server
27. ication the M2M System Protocol 2 objects must be included within application software Listing 2 shows a makefile template that lists the Hello woria and M2M System Protocol 2 object files Listing 2 A sample makefile for the M2M System Protocol 2 Makefile template for the M2M System Protocol 2 Win32 port List all the objects of the M2M System Protocol 2 Notice that Win32 specific file names end with win32 SP2_OBJS sp2_control_api o sp2 socket api o sp2_link_api o Sp2 common Ssp2_es 0 sp2 dll lo sp2 milo spl port socket ORN Spe portos wWins2 o Sp port_hw_win3s2 o sp2_system_common_win32 0 sp2_dbg_wrap_win32 0 Target all contains application software objects instead 39 46 of HelloWorld o in application module software makefile all SP2_OBJS HelloWorld o Tip The Hello world makefile is a good starting point when integrating the M2M System Protocol 2 with application software 40 46 APPENDIX NOKIA 12 GSM MODULE CONFIGURATION FOR THE HELLO WORLD APPLICATION This chapter provides an example of how to use the Nokia 12 Configurator to configure two Nokia 12 GSM modules as a client and a server The configuration presented in this chapter has to be carried out in order for the Hello World Client to establish a connection to the Hello World server The Hello World server configuration The incoming Challenge Handshake Authentication Protocol CHAP for the
28. il all the data has been received int n sp2_ receive socket messageBuffer bytesReceived size bytesReceived 0x00 if n SP2_SOCKET_ERROR printf ERROR sp2_receiveln return isMessageReceived else Check whether the 0 char was received aig EG for i bytesReceived i lt bytesReceivedtn itt if messageBuffer i 0 isMessageReceived TRUE bytesReceived n Yield Let other threads run return isMessageReceived Do the cleanup and then exit void cleanExit int statusId char statusName 38 46 printf Ss n statusName switch statusId Successful case case 0 break Error cases case 10 tlow thou case 20 CloseHandle sp2_hLinkReadyEvent CloseHandle sp2_hStopEvent flow thru case 20 break case 60 ff tlow thru case 50 tlow thru case 40 flow thru aise Syoy_ Sieroys ON system_event_wait sp2_hStopEvent 10 1000 flow thru case 30 system_event_destroy sp2_hStopEvent flow thru case 20 system_event_destroy sp2_hLinkReadyEvent flow thru case 10 break default printf Unknown ERROR at cleanExit d n statusId break The statusId is passed to ExitProcess and it can be acquired by using the Win32 GetExitCodeThread function success 0 ExitProcess statusId To use the M2M System Protocol 2 functions from an appl
29. le the resource requirements for the Win32 reference implementation of the M2M System Protocol 2 are listed in Table 2 Table 2 M2M System Protocol 2 resource requirements Resource Requirement Threads SenderThread ReceiverThread MsgQueueThread RAM Static 4 KB thread stack dynamic approx 20 KB ROM Approx 64 KB 9 46 When the M2M System Protocol 2 is started it will create the SenderThread ReceiverThread and MsgQueueThread The SenderThread and ReceiverThread are high priority serial drivers used for packet sending and receiving respectively The MsgQueueThread takes care of serial message delivery to from the M2M System Protocol protocol stack and its priority is application dependent The M2M System Protocol 2 memory requirements are approx 64 KB ROM without system libraries and approx 4 KB RAM In addition some memory is needed for dynamic memory and thread stacks Dynamic memory size ranges from a few kilobytes to a maximum of 30 kilobytes depending mainly on serial buffer sizes The memory requirement for each thread stack is a few kilobytes Note The Nokia M2M Platform M2M System Protocol 2 Specification also defines a minimum implementation for resource constrained AM devices The Nokia M2M module supports the minimum implementation 10 46 THE M2M SYSTEM PROTOCOL 2 SOCKET INTERFACE The socket interface is divided into the following APIs Socket API M2M
30. n and then starts the M2M System Protocol 2 threads The function call is illustrated in Figure 12 Application software M2M System Protocol 2 Nokia M2M module software sp2_start Configure DLL parameters status and start the threads x 7 al sp2_reset gt RESET m Reset the NLL RESET_RESP Reset the NLL status N Clear packet sequence numbers abort pending transactions and close all sockets Figure 12 Starting the M2M System Protocol 2 The parameters and return values of the sp2_start function call are described in Table 22 and Table 23 Table 22 The sp2_start function call parameters Parameter Description N1 M2M System Protocol 2 parameter N1 50 255 N3 M2M System Protocol 2 parameter N3 5 10 T3 M2M System Protocol 2 parameter T3 1 15s Port Serial port number used for data link connection Baud rate E bit s used 9600 19200 38400 57600 23 46 D Note Typically only the port and baud rate parameters are modified The recommended values for the N1 N3 and T3 parameters are 255 10 and 5 respectively For more information on modifying the N1 N3 and T3 parameter values see the Nokia M2M Platform M2M System Protocol 2 Specification Table 23 The sp2_start function call return values Return
31. nd 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 ACRONYMS AND TERMS Acronym term Description AM Application Module ANSI American National Standards Institute API Application Programming Interface CHAP Challenge Handshake Authentication Protocol DLL Data Link Layer IP Internet Protocol KB Kilobyte equivalent to 1024 bytes M2M Machine to Machine Man to Machine Machine to Man NLL Network Link L
32. number of bytes to be written DWORD flags 0 no flags DWORD bytesWritten number of bytes written successfully bytesWritten sp2_send socketID buff nbytes flags if bytesWritten SP2_SOCKET_ERROR 18 46 5 1 7 Receiving data from a socket sp2_ receive The sp2_receive function instructs the Nokia M2M module to read data from a socket The sp2_receive will block and wait until data is available The function call is illustrated in Figure 9 Application software M2M System Protocol 2 Nokia M2M module software sp2_receive RECEIVE RECEIVE_RESP err_status K L Wait until data is available RECEIVE_NOTIFICATION RECEIVE_NOTIFICATION_RESP y status data In case an error occurs the function returns with an error status Figure 9 Receiving data from a socket The parameters and return values of the sp2_receive function call are described in Table 16 and Table 17 Table 16 The sp2_receive function call parameters Parameter Description Socket ID A handle to the socket from which data is read Buffer Buffer for the data to be read Data length The length of the data to be read in bytes Flags Receive flags Table 17 The sp2_receive function call return values Return value Description Bytes received Number of bytes read successfully SP2 SOCKET ERROR Failure t
33. o receive data An example of receiving data from a socket 19 46 DWORD socketID a handle to the socket BYTE buff DATA LENGTH buffer to store received data DWORD nbytes DATA_LENGTH number of bytes to be read DWORD flags 0 no flags used DWORD bytesRead number of bytes read successfully bytesRead sp2_ receive socketID buff nbytes flags if bytesRead SP2_SOCKET_ERROR 5 1 8 Closing a socket sp2_close The sp2_close function releases a socket handle and instructs the Nokia M2M module to close a socket The function call is described in Figure 10 Application software M2M System Protocol 2 Nokia M2M module software sp2_close status CLOSE A Close the socket CLOSE_RESP Close the socket Figure 10 Closing a socket The parameters and return values of the sp2_close function call are described in Table 18 and Table 19 Table 18 The sp2_close function call parameters Parameter Description Socket ID A handle to the socket to be closed Table 19 The sp2_close function call return values Return value Description SP2_SOCKET_OK Socket was closed successfully SP2_SOCKET_ERROR Failure to close a socket An example of closing a socket 20 46 DWORD socketID a handle to the socket DWORD status a return value from the f
34. receive eeececeeeeeeeeeeeeeeseeeeeteeteeeeneees 19 5 1 8 Closing a socket sp2_ close 20 5 1 9 Resolve host information sp2_gethostbyname eee eeeeeeeeeeeeeeeeeeeeeeeeeeeeees 21 5 1 10 Network utility IUACHIONS sn nn Re Re Int iee 22 5 2 M2M SYSTEM PROTOCOL 2 CONTROL API ie 22 5 2 1 Starting the M2M System Protocol 2 sp2_start 22 5 2 2 Stopping the M2M System Protocol 2 sp2 _ stop 24 5 3 WIRELESS LINK CONTROL APIs dessins 25 5 3 1 Opening a wireless link sp2_link_open 25 5 3 2 Closing a wireless link sp2_link_close eceeeceeeeseeeeeeeeneeeeeeeteeeeeeeenaeeeteees 27 6 EXAMPLE OF M2M SYSTEM PROTOCOL 2 SOCKET USAGE 29 6 1 TYPICAL SOCKET SACR annee andere iesatveibectdiandetnsdpauddceomessnsceemnteawese 29 6 1 1 Using a client SOCKS is nds 29 6 1 2 Using a server SOCKS ss nantes 30 6 2 APPLICATION SOFTWARE EXAMPLE iii 31 6 2 1 Configuring and executing the Hello World application 32 6 2 2 The Hello World implementation c cccceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeneeea 33 APPENDIX NOKIA 12 GSM MODULE CONFIGURATION FOR THE HELLO WORLD APPLICATION eee nnana aa tte telnet 41 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 a
35. rface can also be used to connect an AM application to other remote machines that use IP Because the IP protocol stack placed at the disposal of the socket interface is located on the Nokia M2M module application software must have a connection to the Nokia M2M module services As illustrated in Figure 1 the M2M System Protocol 2 software is used to tunnel IP traffic between the AM and the Nokia M2M module via a serial connection Application Nokia M2M Module module Application M2M module software services Wireless connectivity Socket interface M2M System M2M System Protocol 2 Serial Protocol 2 software connection software Figure 1 M2M System Protocol 2 overview The socket interface provides a standard interface towards application software In addition to socket handling the socket interface makes it possible for the application to control both the wireless and serial connection The M2M System Protocol 2 software connects the AM to the Nokia M2M module via a serial connection link and enables the control of a M2M wireless connectivity link The serial connection is a physical connection between the AM and Nokia M2M module It is connected between a serial port of the AM and the M2M System Connector of the Nokia M2M module The serial connection defines the lowest layer transmission format using a point to point type of serial mode transmission as described in the Nokia M2M Platform M2M System Protocol 2 Specification
36. s of the sp2_1ink_close function call are described in Table 27 and Table 28 Table 27 The sp2_link_close function call parameters Parameter Description Link ID Link ID to be closed Table 28 The sp2_link_close function call return values Return value Description SP2_LINK_OK Link was closed successfully SP2_LINK_ERROR Failure to close a link An example of closing a wireless link 27 46 DWORD linkID a handle to the link if sp2_link_close linkID SP2_LINK_OK 28 46 6 EXAMPLE OF M2M SYSTEM PROTOCOL 2 SOCKET USAGE 6 1 TYPICAL SOCKET USAGE Sockets are typically used for client server communication This chapter describes the typical use of the M2M System Protocol 2 client and server sockets Although the sequences are illustrated from an individual socket s point of view one M2M System Protocol 2 session and wireless GSM link may of course be used for many different sockets 6 1 1 Using a client socket Typically application software that uses a M2M System Protocol 2 client socket over wireless connectivity has to Open a serial link to the Nokia M2M module via the M2M System Protocol 2 Control API Reset the protocol via the M2M System Protocol 2 Control API Open a wireless GSM link via the Wireless Link Control API Communicate with the server application via the Socket API Close the wireless link via the Wireless Link Control API Close the
37. serial link to the Nokia M2M module via the M2M System Protocol 2 Control API A typical client socket message sequence is illustrated in Figure 16 29 46 Socket client M2M System Protocol 2 l Start M2M System Protocol 2 Open a wireless link Wireless link opened notification Create a socket Connect the socket Data sending and receiving Close the socket Close the wireless link Wireless link closed notification Stop M2M System Protocol 2 J Wireless link is not used for local sockets Connect is required only for stream sockets Figure 16 A typical client socket message sequence Note In case the wireless link breaks all new and pending socket functions using the link in question will fail To execute the socket operations that were interrupted the wireless link has to be re established and the sockets have to be closed and recreated 6 1 2 Using a server socket Unlike with client sockets server sockets do not need to control wireless GSM links Instead the Nokia M2M module handles wireless links automatically Typically application software that uses a M2M System Protocol 2 server socket has to 1 Open a serial link to the Nokia M2M module via the M2M System Protocol 2 Control API 2 Reset the M2M System Protocol 2 via the M2M System Protocol
38. t address length Create an M2M System Protocol 2 socket for the server to start listening to client connections serverSocket sp2_socket SP2_AF_INET SP2_SOCK_STREAM SP2_IPPROTO_TCP if serverSocket SP2_SOCKET_ERROR socketAddress sin_family SP2_AF_INET 36 46 socketAddress sin_ port sp2_htons TcpPortThatServerlsListening socketAddress sin_addr 0 if sp2_bind serverSocket sp2_sockaddr amp socketAddress sizeof socketAddress SP2_SOCKET_ERROR if sp2_listen serverSocket 0x00 SP2 SOCKET _ERROR The server is now ready to receive socket connections addrLen sizeof socketAddress socket sp2_accept serverSocket sp2_sockaddr amp socketAddress amp addrLen if socket SP2_SOCKET_ERROR char messageBuffer messageBufferLen if receiveMessage socket messageBuffer messageBufferLen printf Server got message s n messageBuffer if strcemp SAY messageBuffer 0 const char helloWorldString HELLO WORLD printf Server send message s n helloWorldString if sendMessage socket helloWorldString give system time to send message Sleep 3 1000 else printf ERROR Server sp2_send n return FALSE else printf ERROR Server receiveMessage n return FALSE if sp2_close socket SP2_SOCKET_ERROR peinte TERROR Server sp2uclose n return FALSE else printf ERROR
39. te autobaud Gateway port fC Connection timeout fo D Change CHAP Authentication parameters Outgoing CHAP user name Outgoing CHAP password Read parameters Write parameters Figure 20 The Hello World server connection configuration You also have to configure the IP address of the server The IP address that is configured to the server must match with the IP address that the client uses as a parameter for the M2M System Protocol 2 sp2_connect function 5 Select Cable from the IMlet loading menu 6 Write 10 0 0 1 as the Nokia 12 IP address An example IP address configuration for the server is shown in Figure 21 42 46 IMlet Loading an Ma x m File sind jar IMlets Module IMlet list EE Browse Delete Update Start Stop ae status Cancel m Memory usage of module Free fi 187 kB r Nokia 12 IP address 0 0 0 1 Re wie _Urdete_ OK Close Help Figure 21 Hello World server IP address configuration The Hello World client configuration In the Hello World example the client is configured so that it makes a direct TCP CSD call to the server Therefore you need to configure a TCP CSD connection for the client the client opens the default connection when it connects to the server 1 Select Bearer Selection from the M2M System Mode menu 2 Choose the default connection for example Connection 1 An exampl
40. tion address a WTP port SSE Gateway number 123mm Gateway IP address 1 1 1 1 Data call bit rate autobaud Gateway port CE Connection timeout 300 IV Change CHAP Authentication parameters Outgoing CHAP user name TA Outgoing CHAP password TA Read parameters Write parameters re Figure 23 Hello World client configuration for a wireless connection Note In this example the data call is dropped if there is a 300 second pause in the data traffic connection timeout is set to 300 s And finally you also have to configure the IP address of the client The IP address that is configured to the client can be any valid host IP address for example 10 0 0 2 7 Select Cable from the IMlet loading menu 8 Write 10 0 0 2 as the Nokia 12 IP address An example IP address configuration for the client is shown in Figure 24 45 46 IMlet Loading ee x r File loading jar r IMlets PC Module IMlet list a Browse Delete Update Loading status E Cance r Memory usage of module Free i186 kB r Nokia 12 IP address fo o o 2 Reed we pi Start Stop OK Close Help Figure 24 Hello World client IP address configuration 46 46
41. unction status sp2_close socketID if status SP2_SOCKET_OK 5 1 9 Resolve host information sp2_gethostbyname The sp2_gethostbyname function resolves host information based on domain name The function call is illustrated in Figure 11 Application software M2M System Protocol 2 Nokia M2M module software sp2_gethostbyname GETHOSTBYNAME_REQ Resolve host information GETHOSTBYNAME_RESP status Figure 11 Resolving host information The parameters and return values of the sp2_gethostbyname function call are described in Table 20 and Table 21 Table 20 The sp2_gethostbyname function call parameters Parameter Description String A domain name to be resolved Table 21 The sp2_gethostbyname function call return values Return value Description Host information Host information was resolved successfully NULL Failure to resolve a host An example of resolving host information struct hostent host function gethostbyname will reserve memory const char hostname local a domain name host sp2_gethostbyname hostname if host NULL 21 46 5 1 10 5 2 5 2 1 use the host information and then release allocated memory free host gt h_name name string must be released by caller free host host struct must be released by caller finally
42. unication over the network For more information on the socket interface see Chapter 5 NETWORK LINK LAYER The Network Link Layer NLL is used to carry the M2M System Protocol 2 protocol primitives requests responses and indications notifications between the AM and the Nokia M2M module For more information on the NLL see the Nokia M2M Platform M2M System Protocol 2 Specification DATA LINK LAYER The Data Link Layer DLL handles the transmission of protocol data packets between the AM and the Nokia M2M module over a serial connection For more information on the DLL see the Nokia M2M Platform M2M System Protocol 2 Specification 6 46 3 4 PLATFORM WRAPPERS The M2M System Protocol 2 is designed to operate in heterogeneous environments where a variety of operating systems and different types of serial communication hardware are used The operating system and serial communication wrappers separate platform specific functionality from the protocol stack in order to enhance the portability of the M2M System Protocol 2 implementation to different environments For more information on the M2M System Protocol 2 platform wrapping see Chapter 4 7 46 4 INTEGRATING THE M2M SYSTEM PROTOCOL 2 WITH APPLICATION SOFTWARE This chapter describes how the M2M System Protocol 2 is integrated as a part of application software 4 1 SOFTWARE IMPLEMENTATION The M2M System Protocol 2 is provided as ANSI C implementation The software
Download Pdf Manuals
Related Search