MuRata.h

00001 #ifndef SmartLab_MuRata_MuRata
00002 #define SmartLab_MuRata_MuRata
00003 
00004 #include "Payload.h"
00005 #include "UARTFrame.h"
00006 
00007 #include "UARTConfig.h"
00008 #include "DHCPConfig.h"
00009 #include "SoftAPConfig.h"
00010 
00011 #include "CMDCode.h"
00012 #include "SNICCode.h"
00013 #include "WIFICode.h"
00014 
00015 #include "BSSType.h"
00016 #include "CommandID.h"
00017 #include "DHCPMode.h"
00018 #include "HTTPContent.h"
00019 #include "IPAddress.h"
00020 #include "ResetCode.h"
00021 #include "ScanType.h"
00022 #include "SecurityMode.h"
00023 #include "SocketSentOption.h"
00024 #include "SubCommandID.h"
00025 #include "WIFIInfo.h"
00026 #include "WIFINetwork.h"
00027 #include "WIFINetworkDetail.h"
00028 #include "WIFIInterface.h"
00029 #include "WIFIStatusCode.h"
00030 #include "WPSMode.h"
00031 
00032 #include "SSIDRecordIndication.h"
00033 #include "TCPStatusIndication.h"
00034 #include "SocketReceiveInidcation.h"
00035 #include "UDPReceivedIndication.h"
00036 #include "WIFIConnectionIndication.h"
00037 #include "HTTPResponseIndication.h"
00038 
00039 #include "WIFIStatusResponse.h"
00040 #include "InitializationResponse.h"
00041 #include "SendFromSocketResponse.h"
00042 #include "CreateSocketResponse.h"
00043 #include "SocketStartReceiveResponse.h"
00044 #include "DHCPInfoResponse.h"
00045 #include "HTTPResponse.h"
00046 
00047 #include "mbed.h"
00048 
00049 namespace SmartLabMuRata
00050 {
00051 class MuRata
00052 {
00053 private :
00054     SSIDRecordIndication _SSIDRecordIndication;
00055     WIFIConnectionIndication _WIFIConnectionIndication;
00056     TCPStatusIndication _TCPStatusIndication;
00057     SocketReceiveInidcation _SocketReceiveInidcation;
00058     UDPReceivedIndication _UDPReceivedIndication;
00059     HTTPResponseIndication _HTTPResponseIndication;
00060 
00061     WIFIStatusResponse _WIFIStatusResponse;
00062     InitializationResponse _InitializationResponse;
00063     SendFromSocketResponse _SendFromSocketResponse;
00064     DHCPInfoResponse _DHCPInfoResponse;
00065     SocketStartReceiveResponse _SocketStartReceiveResponse;
00066     CreateSocketResponse _CreateSocketResponse;
00067     HTTPResponse _HTTPResponse;
00068 
00069     IPAddress ip;
00070 
00071     Serial * serial;
00072     Payload _payload;
00073     UARTFrame _frame;
00074 
00075     void Send();
00076 
00077     bool FrameReceive();
00078 
00079     CreateSocketResponse * SNIC_CreateSocket(const SubCommandID subID, const bool bind = false, IPAddress * localIP = NULL, const int localPort = 0);
00080 
00081     /// Time out when there is no data received
00082     Timer timer;
00083 
00084 public:
00085 
00086     static const int DEFAULT_BAUDRATE = 921600;
00087 
00088     // ##############################################################################
00089     //                                indication
00090     // ##############################################################################
00091 
00092     SSIDRecordIndication * Get_ScanResultIndication();
00093 
00094     WIFIConnectionIndication * Get_WiFiStatusIndication();
00095 
00096     /**
00097     * This event reports the Murata module power up reason. Murata module is ready for serial communication after this report is generated.
00098     * @return N0_Indication when no response is received.
00099     */
00100     ResetCode Get_PowerUpIndication();
00101 
00102     TCPStatusIndication * Get_TcpConnectionStatusIndication();
00103 
00104     SocketReceiveInidcation * Get_SocketReceiveIndication();
00105 
00106     UDPReceivedIndication * Get_UDPReceiveIndication();
00107 
00108     HTTPResponseIndication * Get_HTTPResponseIndication();
00109 
00110     // ##############################################################################
00111     //                                constructor
00112     // ##############################################################################
00113 
00114     /**
00115     * Constructor
00116     * @param tx mbed pin name for UART
00117     * @param rx mbed pin name for UART
00118     */
00119     MuRata(PinName tx, PinName rx);
00120 
00121     /**
00122     * Constructor
00123     * @param tx mbed pin name for UART
00124     * @param rx mbed pin name for UART
00125     * @param baudrate serial baud rate
00126     * @param bits
00127     * @param parity
00128     * @param stop_bits
00129     */
00130     MuRata(PinName tx, PinName rx, int baudrate ,int bits=8, Serial::Parity parity=SerialBase::None, int stop_bits=1);
00131 
00132 
00133     // ##############################################################################
00134     //                                   GEN
00135     // ##############################################################################
00136 
00137     /**
00138     * SNIC firmware has a built in version string. Use this command to retrieve the version info.
00139     * @returns return null when timeout
00140     */
00141     const char * GEN_GetFirmwareVersionInfo();
00142 
00143     /**
00144     * This command restores the data stored in NVM to factory default values. Any web page update is not affected by this command.
00145     * A soft reset will be performed automatically after the NVM has been restored.
00146     * Application needs to send WIFI_GET_STATUS_REQ or SNIC_GET_DHCP_INFO_REQ commands to determine the new state of the Murata module.
00147     */
00148     CMDCode GEN_RestoreNVMtoFactoryDefault();
00149 
00150     /**
00151     * This command resets the module. Application needs to send WIFI_GET_STATUS_REQ or SNIC_GET_DHCP_INFO_REQ commands to determine the new state of the module after the reset.
00152     */
00153     CMDCode GEN_SoftReset();
00154 
00155     /**
00156     * This command configures the UART interface. The specified parameters are saved into the NVM and they are used for the specified UART interface in subsequent powerups.
00157     */
00158     CMDCode GEN_UARTConfiguration(UARTConfig * config);
00159 
00160     // ##############################################################################
00161     //                                   WiFi
00162     // ##############################################################################
00163 
00164     /**
00165     * This command turns on Wifi on module.
00166     * The default country code is “US”, which is one of the startup parameters in NVM. If the WIFI_ON_REQ has no intention of changing the country code, put 0x0000 in the two-byte Country code, so that the firmware will use the country code configured in NVM.
00167     * The module supports both soft AP mode and STA mode at the same time. The module has reserved flash space (NVM) to store startup parameters for both the soft AP and the STA. Only STA’s parameters can be dynamically changed at run time.
00168     * Turning on WiFi would cause the following to happen:
00169     * The following operations occur using the parameters specified in the NVM if the AP mode is enabled.
00170     * 1. Turn on the soft AP
00171     * 2. Starts DNS server, DHCP server and HTTP server. The HTTP server provides a means for configuring the WLAN access parameters for the STA.
00172     * Turn on the STA. If the NVM has valid startup parameters, the STA will try to join the saved SSID with saved authentication information. The NVM also stores whether DHCP or static IP is used for STA. If DHCP is used, DHCP client will be started. After a successful join, STA’s IP will be configured according to the NVM.
00173     * By default, the soft AP is turned on to allow user to use a WiFi enabled computer to connect to the soft AP, and instructs the STA to join one of the surrounding APs. So WiFi is turned on by default and this command is not required at startup.
00174     */
00175     WIFICode WIFI_TurnOn();
00176 
00177     /**
00178     * This command turns off Wifi on module. Turning off WiFi causes the following to happen:
00179     * 1. Turn off the soft AP, including shutting down DNS server, DHCP server and HTTP server.
00180     * 2. Disconnect STA from any joined network, and close all sockets opened by application.
00181     */
00182     WIFICode WIFI_TurnOff();
00183 
00184     /**
00185     * This command turns on or off the soft AP. The WIFI_ON(OFF)_REQ controls both the soft AP and STA at the same time, while this command only controls the soft AP.
00186     * An example use case is, the soft AP (and its web server) is turned on at startup to configure STA to join a network and is no longer needed after the STA is connected.
00187     * WIFI_AP_CTRL_REQ can be used to turn the soft AP off.
00188     * OnOff = 0 indicates AP is to be turned off. The rest of the parameters are ignored.
00189     * OnOff = 1 indicates turning on soft AP using existing NVM parameters,
00190     * OnOff = 2 indicates turning on AP with the parameters provided. If the soft AP is already on, it is first turned off.
00191     * Persistency=1 indicates the soft AP’s on/off state and parameters (if OnOff = 2) will be saved in NVM. For example, if OnOff =0 and Persistency=1, the soft AP will not be turned on after a reset.
00192     */
00193     WIFICode WIFI_SoftAPControl(SoftAPConfig * config);
00194 
00195     /**
00196     * This command instructs module to associate to a network.
00197     */
00198     WIFICode WIFI_AssociateNetwork(WIFINetwork * AP);
00199 
00200     /**
00201     * This command instructs the module to disconnect from a network.
00202     * Upon a successful reception of the command, the module disconnects from associated network. Sockets opened by application are not closed.
00203     */
00204     WIFICode WIFI_DisconnectNetwork();
00205 
00206     /**
00207     * This command queries the WiFi status from module. This command should be called by application after startup to determine the WiFi status since the module may have joined an AP automatically based on NVM parameters (see 6.1).
00208     * </summary>
00209     */
00210     WIFIStatusResponse * WIFI_GetStatus(const WIFIInterface WiFiInterface);
00211 
00212     /**
00213     * This command requests the reporting of the current RSSI from module’s STA interface
00214     * @returns RSSI in dBm. 127 means unspecified value
00215     */
00216     int8_t WIFI_GetRSSI();
00217 
00218     /**
00219     * This command requests the module to use WPS to join the network. Two methods are supported: push button and pin-based configuration.
00220     * If Mode is 1, Pin value must be present. Pin value is NUL terminated ASCII string. Pin string length of 0, 4, 7, or 8 is valid. When length is 0, the module will use the WPS default pin configured in the NVM by using the SNIC monitor. When length is 8, the 8th digit must be the correct checksum of the first 7 digits. The pin checksum calculation method can be found from the Internet. When the length is 7, the module firmware will calculate the checksum automatically. When the length is 4, no checksum is required.
00221     * Upon a successful reception of the command, the module tries to associate to a network using the WPS configuration specified. Upon a successful completion of the join process, the SSID and authentication parameters will be saved in NVM which will be used in subsequent power up (see 6.1).
00222     */
00223     WIFICode WIFI_StartWPSProcess(const WPSMode mode, const char * pin = NULL, int pinLength = 0);
00224 
00225     /**
00226     * Upon a successful reception of the command, the module starts to scan. The response will indicate only WIFI_SUCCESS if no error. Actual scan result shall be sent from module as multiple indications defined in WIFI_SCAN_RESULT_IND
00227     * </summary>
00228     * @param scan
00229     * @param bss
00230     * @param BSSID 6 bytes MAC address of the AP or STA
00231     * @param channelList up to 10 array elements
00232     * @param SSID string for the AP or STA SSID, up to 32 bytes
00233     */
00234     WIFICode WIFI_ScanNetworks(const ScanType scan, const BSSType bss);
00235 
00236     // ##############################################################################
00237     //                                   SNIC
00238     // ##############################################################################
00239 
00240     /**
00241     * This command initializes the SNIC networking framework on module. TCP/UDP socket communication may be performed only after this command is called.
00242     * The Default receive buffer size is the default maximum size of receive buffer in the module. If 0 is specified, a system defined value (2048) will be used. If there is a Receive buffer size field in other commands, then it must be less than or equal to the Default receive buffer size. If the Receive buffer size in any of those commands is 0, the Default receive buffer size will be used.
00243     * @param  receiveBufferSize Upon a successful reception of the command, the module sends to the host the following response. If user specified Default receive buffer size is bigger than what the module can handle, the system defined value will be returned in the response; otherwise, user specified Default receive buffer size will be retuned. Maximum number of UDP and TCP sockets supported by module will also be returned.
00244     */
00245     InitializationResponse * SNIC_Initialization(int receiveBufferSize = 0);
00246 
00247     /**
00248     * This command closes the SNIC networking framework on module. It should cleanup resources for socket communication on module. If some sockets are not closed, this command will close all of them. No more network communication can be performed until SNIC_INIT_REQ is called.
00249     */
00250     SNICCode SNIC_Cleanup();
00251 
00252     /**
00253     * In TCP server case, Socket is the socket number returned by SNIC_TCP_CLIENT_SOCKET_IND. In TCP client case, Socket can be either from SNIC_CONNECT_TO_TCP_SERVER_RSP, or from the SNIC_TCP_CONNECTION_STATUS_IND with SNIC_CONNECTION_UP status. In UDP case, Socket is the socket number returned by SNIC_UDP_CREATE_SOCKET_REQ and it must be in connected mode.
00254     * A success response of this command does not guarantee the receiver receives the packet. If error occurs, a SNIC_TCP_CONNECTION_STATUS_IND with SNIC_SOCKET_CLOSED will be sent to the application in TCP case. No indication will be sent in UDP case.
00255     * Option is the action module will perform to the socket after the send operation. Use it when application is sure to close or shutdown the connection after sending. The effect is the same as using SNIC_CLOSE_SOCKET_REQ, but round-trip UART traffic is reduced.
00256     */
00257     SendFromSocketResponse * SNIC_SendFromSocket(const char SocketID, const SocketSentOption option, const char * payload, int offset, int length);
00258 
00259     /**
00260     * This command instructs the module to close a socket.
00261     */
00262     SNICCode SNIC_SloseSocket(const char SocketID);
00263 
00264     /**
00265     * This command queries the DHCP information for a particular interface.
00266     */
00267     DHCPInfoResponse * SNIC_GetDHCPInfo(const WIFIInterface wifiInterface);
00268 
00269     /**
00270     * This command converts a remote host name to IP address.
00271     * Interface number is either 0 or 1. 0 indicates STA interface. 1 indicates soft AP interface. Currently only STA interface is supported.
00272     * If multiple SNIC_RESOLVE_NAME_REQ’s need to be sent, it is required they be sent sequentially due to resource limitation. If the name is not resolved, it takes up to 15 seconds for the failure response to come back. While waiting for the response, host application can send other commands (except for SNIC_RESOLVE_NAME_REQ and SNIC_SEND_ARP_REQ).
00273     */
00274     IPAddress * SNIC_ResolveHostName(const char * host);
00275 
00276     /**
00277     * This command instructs module configure the mechanism for obtaining the IP address.
00278     * DHCP mode specifies how the address is assigned for the interface.
00279     *  0: interface is assigned the static IP, NetMask and Gateway IP. First IP and Last IP are not present. Any active DHCP client or server is stopped.
00280     *  1: STA interface uses DHCP to obtain the address. All subsequent fields are not present. STA DHCP client is started if necessary.
00281     *  2: only for AP interface. If the soft AP is not started or SNIC_INIT_REQ is not done, this command fails. Otherwise, this command stops the HTTP server, DNS server and DHCP server if configured, and restarts them with new parameters. It assigns IP for clients in range [First IP, Last IP] within the subnet mask. The AP itself is assigned the address within the same subnet specified by IP which must not be in the range of [First IP, Last IP]. The value of GTW IP and IP should be the same. If there are clients connected to the soft AP before this command, make sure the clients reconnect to the soft AP after this command.
00282     */
00283     SNICCode SNIC_ConfigureDHCPorStaticIP(DHCPConfig * config);
00284 
00285     /**
00286     * If the connect attempt is immediately completed, the response will contain SNIC_SUCCESS status, with the actual Receive buffer size.
00287     * If the connect attempt is not immediately completed, the response will have the SNIC_COMMAND_PENDING status. The Timeout value is the time (in seconds) the module will wait before aborting the connection attempt. If timeout occurs, the SNIC_TCP_CONNECTION_STATUS_IND indication with SNIC_TIMEOUT status will be sent to the application. If connection is successful before timeout, the SNIC_TCP_CONNECTION_STATUS_IND with SNIC_CONNECTION_UP status will be sent to the application. Timeout value should be non-zero.
00288     * @param remoteHost
00289     * @param port
00290     * @param timeout in seconds
00291     * @param receiveBufferSize Receive buffer size is the maximum packet size the application wants to receive per transmission. It must be less than or equal to the Default receive buffer size from SNIC_INIT_REQ in the module. If it is 0 or exceeds the system capability, the Default receive buffer size is returned.
00292     */
00293     SocketStartReceiveResponse * SNIC_ConnectTCPServer(const char SocketID, IPAddress * remoteIP, const int remotePort, const char timeout, const int receiveBufferSize = 0);
00294 
00295     /**
00296     * If Bind option is 0, the socket will not be bound, and Local IP address and Local port should not be present. Otherwise, it will be bound to Local IP address and Local port specified. 0x0 for IP or port are valid, which means system assigned. Port number 5000 is reserved for internal use.
00297     * the socket number must get and store separately, since the response payload may change
00298     * @param bing do not bing if this tcp socket is used as a client
00299     * @param localIP
00300     * @param localPort
00301     */
00302     CreateSocketResponse * SNIC_CreateTCPSocket(const bool bind = false, IPAddress * localIP = NULL, const int localPort = 0);
00303 
00304     /**
00305     * If Bind option is 0, the socket will not be bound, and Local IP address and Local port should not be present. Otherwise, it will be bound to Local IP address and Local port specified. 0x0 for IP or port are valid, which means system assigned. Port number 5000 is reserved for internal use.
00306     * the socket number must get and store separately, since the response payload may change
00307     * @param bind
00308     * @param localIP
00309     * @param localPort
00310     */
00311     CreateSocketResponse * SNIC_CreateUDPSocket(const bool bind = false, IPAddress * localIP = NULL, const int localPort = 0);
00312 
00313     /**
00314     * The Socket should have been created by command SNIC_UDP_CREATE_SOCKET_REQ. The same socket can be used in SNIC_UDP_SEND_FROM_SOCKET_REQ command, so that send and receive can be done via the same socket (port). The application is responsible to close the socket using SNIC_CLOSE_SOCKET_REQ.
00315     * Receive buffer size is the maximum packet size the application wants to receive per transmission. It must be less than or equal to the Default receive buffer size from SNIC_INIT_REQ in the module. If 0 or exceeds the system capability, the Default receive buffer size will be used and returned in the response.
00316     * After this command, the Socket can receive any UDP sender with connected mode or non-connected mode. The module will generate SNIC_UDP_RECV_IND indication for incoming data, which includes sender’s IP and port info.
00317     * But if this Socket is later connected to a peer UDP server by SNIC_UDP_SEND_FROM_SOCKET_REQ with Connection mode set to1, the module will generate SNIC_CONNECTION_RECV_IND indication without the sender’s IP and port info. See Section 5.19. After that, this Socket will only be able to receive from the one sender it connects to.
00318     */
00319     SocketStartReceiveResponse * SNIC_StartUDPReceive(const char SocketID, const int receiveBufferSize = 0);
00320 
00321     /**
00322     * A socket will be created for sending the packet out through the default network connection, but will be closed after the transmission. This command can be used when the application just wants to send out one packet to peer, and it also does not expect to receive any packets from peer.
00323     */
00324     SendFromSocketResponse * SNIC_SendUDPPacket(IPAddress * remoteIP, const int remotePort, const char * payload, const int offset, const int length);
00325 
00326     /**
00327     * The Socket should have been created by command SNIC_UDP_CREATE_SOCKET_REQ. If SNIC_UDP_START_RECV_REQ is not called on the socket, the application can only send out UDP packet from this socket. If SNIC_UDP_START_RECV_REQ has been called for this socket, the application can send and receive UDP packets from the socket. This implies the application can send and receive packets from the same local port. The application is responsible to close the socket using SNIC_CLOSE_SOCKET_REQ.
00328     * If Connection mode is 1, the module will first connect to the UDP server then send data. Since the socket is still connected after the call, application can send subsequent data using another command SNIC_SEND_FROM_SOCKET_REQ.
00329     * The benefit of the connected mode is that subsequent send can use SNIC_SEND_FROM_SOCKET_REQ, which does not require the receiver’s IP and port every time, and thus reduces overhead. If this socket is also used to receive by calling SNIC_UDP_START_RECV_REQ, the receive indication to the host will also omits the sender IP and port info, further reducing overhead.
00330     * <param name="remoteIP"></param>
00331     * <param name="remotePort"></param>
00332     * <param name="SocketID"></param>
00333     * <param name="connectServer"></param>
00334     * <param name="payload"></param>
00335     * <param name="offset"></param>
00336     * <param name="length"></param>
00337     */
00338     SendFromSocketResponse * SNIC_SendUDPFromSocket(IPAddress * remoteIP, const int remotePort, const char SocketID, const bool connectServer, const char * payload, int offset, const int length);
00339 
00340     /**
00341     * This command instructs the module to send a HTTP request packet to the remote HTTP server.
00342     * Post content can be binary. So even if it is text string, it should not contain NUL at the end. The most significant bit of Post content length is reserved to indicate if there is more data to send. If there is more data to send (as indicated by MSBit=1 in the content length), host application should use another API (SNIC_HTTP_MORE_REQ) to send the rest of the data until it is finished. If this bit is set to 1, then the “Transfer-Encoding” in the HTTP request will be set to “chunked” by SNIC. For GET method, the highest bit of Content length must be set to 0 (not chunked).
00343     * For HTTP request with chunked encoding, status code of SNIC_SUCCESS in the response only means the HTTP request has been sent. After one or more subsequent SNIC_HTTP_MORE_REQ/RSPs, the last SNIC_HTTP_MORE_RSP with HTTP status code will be sent to host containing the data from HTTP server.
00344     * The most significant bit of Content length is reserved to indicate if there is more response data to send to the host. If there is more data to send (Content length MSBit=1), module uses SNIC_HTTP_RSP_IND to send the rest of the data until it is finished, i.e., when this bit is 1, the host application should continue to receive SNIC_HTTP_RSP_IND, until this bit is 0.
00345     * The Content length is limited by the receive buffer size specified in SNIC_INIT_REQ and the system resource at that moment.
00346     * <param name="content"></param>
00347     * <param name="isHTTPS"></param>
00348     * <param name="chunked"></param>
00349     */
00350     HTTPResponse * SNIC_SendHTTPRequest(HTTPContent * content, const bool isHTTPS = false, const bool chunked = false);
00351 
00352     /**
00353     * This command instructs the module to send a subsequent HTTP request packet to the remote HTTP server if the initial SNIC_HTTP_REQ cannot finish the packet due to size or other consideration. It is used when the send method is POST.
00354     * <param name="content"></param>
00355     * <param name="chunked"></param>
00356     */
00357     HTTPResponse * SNIC_SendHTTPMoreRequest(HTTPContent * content, const bool chunked = false);
00358 
00359     /**
00360     * If Bind option is 0, the socket will not be bound, and Local IP address and Local port should not be present. Otherwise, it will be bound to Local IP address and Local port specified. 0x0 for IP or port are valid, which means system assigned. Port number 5000 is reserved for internal use.
00361     * the socket number must get and store separately, since the response payload may change
00362     * </summary>
00363     * <param name="bing">do not bing if this tcp socket is used as a client</param>
00364     * <param name="localIP"></param>
00365     * <param name="localPort"></param>
00366     */
00367     CreateSocketResponse * SNIC_CreateAdvancedTLSTCP(const bool bind, IPAddress * localIP = NULL, const int localPort = 0);
00368 
00369     /**
00370     * If Bind option is 0, the socket will not be bound, and Local IP address and Local port should not be present. Otherwise, it will be bound to Local IP address and Local port specified. 0x0 for IP or port are valid, which means system assigned. Port number 5000 is reserved for internal use.
00371     * the socket number must get and store separately, since the response payload may change
00372     * </summary>
00373     * <param name="bind"></param>
00374     * <param name="localIP"></param>
00375     * <param name="localPort"></param>
00376     */
00377     CreateSocketResponse * SNIC_CreateSimpleTLSTCP(const bool bind, IPAddress * localIP = NULL, const int localPort = 0);
00378 
00379 };
00380 }
00381 
00382 #endif