Wi-Fi Module WX library  v0.80
Collection of convenience functions for the Parallax WX Wi-Fi Module
Functions
wifi.h File Reference

API for the Parallax WX Wi-Fi Module ESP8266-WROOM-02 (Part #32420). This library has a preliminary API that provides a starting point for some examples in the publication queue, and also for the Parallax open source community to build and improve upon. More...

#include "simpletools.h"
#include "fdserial.h"

Go to the source code of this file.

Macros

wifi_start function constants
#define WX_ALL_COM   -1
#define USB_PGM_TERM   -2
#define USB_PGM   -3
Serial Command Tokens
#define ARG   0xE6
 Command token for retrieving a GET or POST request's name argument.
#define CONNECT   0xE4
 Command token for attempting to establish a TCP connection.
#define CLOSE   0xE8
 Command token for terminating a connection or listiner with either its ID or handle.
#define CHECK   0xEE
 Command token used to check a Wi-Fi module setting or I/O pin state.
#define JOIN   0xEF
 Command token for joining a network.
#define LISTEN   0xE7
 Command token for setting up a listener process that monitors HTTP or WebSocket activity.
#define PATH   0xEB
 Command token used to check the path that is associated with a connection handle listener ID.
#define POLL   0xEC
 Command token used to poll for events on paths that have listeners or connections set up.
#define RECV   0xE9
 Command token for retrieving TCP/WebSocket data or HTTP body.
#define REPLY   0xE5
 Command token for transmitting HTTP data in response to a GET or POST request.
#define SEND   0xEA
 Command token used for SENDing TCP, WebSocket, or extended HTTP body data.
#define SET   0xED
 Command token used to "set" a Wi-Fi module setting or I/O pin state.
Serial Parameter Tokens
#define AP   0xF3
 Token that can be used for both setting up and checking the Wi-Fi module's access point mode. In this mode, the Wi-Fi module is an access point that provides wireless (but not Internet) access.
#define CMD   0xFE
 Begin marker token placed at the start of serial commands to the Wi-Fi module. Data that does not appear between CMD and '\r' is passed through as transparent serial data. CMD is also used in wifi_print/scan's type parameter to tell it to treat the formatted data to/from the Wi-Fi module as a command.
#define GET   'G'
 A token returned by POLL to indicate that a GET request with a path that matched one on a listener has been received by the Wi-Fi module.
#define HTTP   0xF7
 One of the argument option tokens that can be used with the LISTEN command token to set up an HTTP event listener.
#define POST   'P'
 A token returned by POLL to indicate that a POST request with a path that matched one set up on a listener has been received by the Wi-Fi module. Also used in wifi_scan's type parameter to tell it to treat the formatted data to/from the Wi-Fi module as WebSocket data.
#define STA   0xF4
 Token used for both setting up and indicating station mode. In this mode, the Wi-Fi module is a station on a wireless network that is hosted by some other access point.
#define STA_AP   0xF2
 Token used for both setting up and indicating station plus access point mode. This mode should only be used when searching for networks and joining one. After the Wi-Fi module has joined another access point, it should be switched to STA mode.
#define TCP   0xF5
 Constant that can be passed to the wifi_print/scan's type parameter to tell it to treat the formatted data to/from the Wi-Fi module as TCP data.
#define WS   0xF6
 One of the argument option tokens that can be used with the LISTEN command token to set up a WebSocket event listener. This token can also be returned by POLL to indicate that a WebSocket request matching a listener ID's path has been received. Also used in wifi_print/scan's type parameter to tell it to treat the formatted data to/from the Wi-Fi module as WebSocket data.
Module I/O Constants
#define GPIO_DI   1
 Token used with the CHECK command to check the 1/0 input state of the Wi-Fi module's DI pin.
#define GPIO_DO   3
 Token used with the SET command to set the 1/0 output state of the Wi-Fi module's DO pin.
#define GPIO_RTS   15
 Token used with the SET command to set the 1/0 output state of the Wi-Fi module's //RTS pin.
#define GPIO_CTS   13
 Token used in conjunction with the SET/CHECK command tokens to set/check the 1/0 output/input states of the Wi-Fi module's /CTS pin.
#define GPIO_ASC   5
 Token used with the SET command token to set the 1/0 output state of the Wi-Fi module's ASSOC pin.
#define GPIO_DBG   2
 Token used with the SET command token to set the 1/0 output state of the Wi-Fi module's DBG pin.
#define GPIO_PGM   0
 Token used with the CHECK command to check the 1/0 input state of the Wi-Fi module's PGM pin.
Error Codes
#define INVALID_REQUEST   1
 Error Code for invalid request.
#define INVALID_ARGUMENT   2
 Error code for invalid argument.
#define WRONG_ARGUMENT_COUNT   3
 Error code for incorrect argument count.
#define NO_FREE_LISTENER   4
 Error code indicating all event listeners are in use.
#define NO_FREE_CONNECTION   5
 Error code indicating all connections are in use.
#define LOOKUP_FAILED   6
 Error code indicating lookup failed.
#define CONNECTION_FAILED   7
 Error code indicating that the connection failed.
#define SEND_FAILED   8
 Error code indicating that the send operation failed.
#define INVALID_STATE   9
 Error code indicating the Wi-Fi module is in an invalid state.
#define INVALID_SIZE   10
 Error code indicating that an invalid size argument was received.
#define DISCONNECTED   11
 Error code indicating that a disconnect occurred.
#define NOT_IMPLEMENTED_ERROR_12   12
 Error code not inplemented.
#define BUSY   13
 Error code indicating that the module is busy.
#define INTERNAL_ERROR   14
 Error indicating that an unspecified error occurred in the Wi-Fi module.
Network Codes
#define NO_ERROR   0
 Accopanies the 'S' for success, example: [0xFE]S,0[0x0D].
#define OUT_OF_MEMORY   -1
 Network code indicating that the module is out of memory.
#define UNDEFINED_NEG2   -2
 Not yet defined.
#define TIMEOUT   -3
 Network code for indicating that a timeout occurred.
#define ROUTING_PROBLEM   -4
 Network code indicating a routing problem occurred.
#define OPERATION_IN_PROCESS   -5
 Network code indicating that an operatino is in proress.
#define UNDEFINED_NEG6   -6
 Undefined.
#define NUMBER_TOO_LARGE   -7
 Network code indicating that a number was too large.
#define CONNECTION_ABORTED   -8
 Nework code indicating that a connection was aborted.
#define CONNECTION_RESET   -9
 Network code indicating that the connection was reset.
#define CONNECTION_CLOSED   -10
 Network code indicating that the connection was closed.
#define NOT_CONNECTED   -11
 Network code indicating that the module is not connected.
#define ILLEGAL_ARGUUMENT   -12
 Network code indicating an illegal argument was received.
#define UNDEFINED_NEG13   -13
 Undefined number 13.
#define UDP_SEND_ERROR   -14
 Network code indicating that a UDP send error occurred.
#define ALREADY_CONNECTED   -15
 Network code allerting that an attempt was made to create a connection that has already been established.
#define SSL_HANDSHAKE_FAILED   -28
 Network code indicating that an SSL handshake failed.
#define SSL_APPLICATION_INVALID   -61
 Network code indicating that an SSL application is invalid.

Functions

char * wifi_bufferSize (int bytes)
 Sets the size (in bytes) of the Wi-Fi communication buffer.
char * wifi_command (char *command)
 Send a string command to the Wi-Fi module using its serial protocol, and get the Wi-Fi module's response. For more information on the serial protocol, consult the Serial Commands section in the Parallax Wi-Fi Module Firmware Guide. It's in the Downloads section of the Wi-Fi module's product page (search for 32420) at www.parallax.com. Example: reply = wifi_command("SET:pin-gpio13,1\\r"); // Set Wi-Fi module's /CTS pin to output-high.
int wifi_connect (char *address, int port)
 Attempt a TCP connection to address on port.
int wifi_disconnect (int idOrHandle)
 Terminate an established connection or listener via its handle or id (respectively), freeing it to rejoin the available connection or listener pools.
int wifi_ip (int mode, int *ipAddr)
 Check the IP address for the Parallax Wi-Fi module.
int wifi_join (char *network, char *password)
 Attempt to join a network via the ssid access point using passphrase.
int wifi_leave (int newMode)
 Leave an AP network and transition into a mode that's not pure STA. The wi-fi module will forget the current station IP address.
int wifi_listen (char protocol, char *path)
 Activate a listener process to monitor HTTP or WebSocket protocol activity on port 80 with a specified path.
int wifi_mode (int mode)
 Set or check the Wi-Fi module's network mode.
void wifi_poll (int *event, int *id, int *handle)
 Check for activity like incoming HTTP GET/POST requests, HTTP/WebSocket/TCP connections/disconnections, and incoming WebSocket/TCP data. Example: int event, id, handle;...wifi_poll(&event, &id, &handle);.
int wifi_print (int protocol, int handle, const char *fmt,...)
 The Wi-Fi module version of the simpletext library's print function. It simplifies formatting data in strings that can be: Responses to GET requests, WebSocket data transmitted, serial commands to the Wi-Fi module, and outgoing TCP messages. This function can be called to send unsolicited data to a WebSocket, a serial command to a Wi-Fi module, or for transmitting a TCP string. It can also be called to reply to an HTTP GET request, which is indicated by wifi_poll storing 'G' in the event variable.
int wifi_recv (int handle, char *data, int size)
 Retrieve incoming HTTP body or WebSocket/TCP data.
int wifi_replyStringCopy (char *targetStr)
 Copy a reply from the libwifi response buffer to a character array.
int wifi_scan (int protocol, int handle, const char *fmt,...)
 The Wi-Fi module version of the simpletext library's scan function. It simplifies extracting data contained in strings from incoming POST requests, WebSocket data, responses to commands, and TCP messages. This Function can be called after the wifi_poll function has sent event information that an incoming request//response/message is ready for the Propeller to receive. This command has a variety of usage examples in the /Examples/Propeller C subfolder of parallax-esp-2016-11-02-1804b and newer. The zip file with this folder is in the downloads section of the Parallax Wi-Fi Module page at www.parallax.com (search 32420).
char wifi_send (int handle, char *data, int size)
 Transmit WebSocket/TCP data, or extended HTTP body (after REPLY command).
void wifi_setBuffer (char *buffer, int size)
 Sets the Wi-Fi buffer to an user declared external character array.
fdserial * wifi_start (int fromDO, int toDI, int baud, int comSelect)
 Set up Wi-Fi module serial connections for data command and transparent data communication.
void wifi_stop (void)
 Stops the process started by wifi_start and recovers any memory that was allocated for command/reply storage and parsing.

Detailed Description

API for the Parallax WX Wi-Fi Module ESP8266-WROOM-02 (Part #32420). This library has a preliminary API that provides a starting point for some examples in the publication queue, and also for the Parallax open source community to build and improve upon.

Author
Andy Lindsay
Version
0.81 for firmware 1.0

Examples that demonstrate a collection of applications that use this library are in the 32420-Parallax-ESP-...zip archive's .../Examples/Propeller C folder. It's available from the Downloads sections on the Parallax WX Wi-Fi Module pages at www.parallax.com (search 32420). Look for the "Parallax WX Wi-Fi Module Firmware and Example Files" link. Make sure to unzip to a folder and open the programs from there, not from within the .zip itself!

Also, make sure to update the Wi-Fi module's firmware. The Parallax ESP.ota file is in the top directory of the same .zip where you got the examples, and update instructions are in learn.parallax.com/propeller-c-wx-wi-fi. The code examples have web addresses to application circuits in the comments, and tutorials will come online, one at a time in the learn.parallax.com/propeller-c-wx-wi-fi pages.

This library was designed to keep a variety of connection options open for the Propeller Activity Board (WX and pre-WX) as well as other boards. It was also designed to coexist with the Simple Libraries that come with SimpleIDE. The goal was to make sure that all the familiar features could be used with a minimum of caveats and memory penalties.

Parallax encourages the open source community to expand this library, the pool of examples, and even the module firmware itself. Here are the project locations on the Parallax GitHub. Make sure to branch, modify, and then submit a pull request. We'd also like to encourage you to visit the Issues tab in these repositories if you run across something that looks like a bug or misprint, or if you have suggestions for improvement.

The example programs make heavy use of the wifi_print and wifi_scan funcitons. They behave similarly to the print and scan functions for SimpleIDE terminal and are intended to be helpful to folks who might just be "getting their feet wet" with IoT.

There's also a wifi_command function that is somewhat less restrictive, allowing programmers to form the command strings and parse all the module responses. For best results, use it in conjunction with the Wi-Fi module's Serial API document. (The Serial API is also in the Downloads section on the Wi-Fi module product page, with a link named Parallax Wi-Fi Module Firmware Guide and a filename of "32420-Parallax-Wi-Fi-Module-API-v...pdf". We hope that this will be helpful in prototyping new functions that supply a more intermediate level of granularity or enhance the educational experience of using these modules with the Propeller.

To Do:

Definition in file wifi.h.

Macro Definition Documentation

#define USB_PGM   -3

Argument option for the wifi_start function's comSelect parameter. USB_PGM runs programming data through USB. Terminal and Wi-Fi application communication are routed from selected I/O pins through the Activity Board's DI and DO sockets.

Definition at line 125 of file wifi.h.

#define USB_PGM_TERM   -2

Argument option for the wifi_start function's comSelect parameter. USB_PGM_TERM runs programming and terminal data through USB. Wi- Fi application communication is routed from selected I/O pins through the Activity Board's DI and DO sockets.

Definition at line 114 of file wifi.h.

#define WX_ALL_COM   -1

Argument option for the wifi_start function's comSelect parameter. WX_ALL_COM makes the Propeller microcontroller send/receive command and terminal data through the Wi-Fi module assuming that the WX Activity Board's SEL pin has been pulled high.

Definition at line 103 of file wifi.h.

Function Documentation

char* wifi_bufferSize ( int  bytes)

Sets the size (in bytes) of the Wi-Fi communication buffer.

Parameters
bytesNumber of bytes the buffer should be.
Returns
*buffer A pointer to the buffer that was created.
char* wifi_command ( char *  command)

Send a string command to the Wi-Fi module using its serial protocol, and get the Wi-Fi module's response. For more information on the serial protocol, consult the Serial Commands section in the Parallax Wi-Fi Module Firmware Guide. It's in the Downloads section of the Wi-Fi module's product page (search for 32420) at www.parallax.com. Example: reply = wifi_command("SET:pin-gpio13,1\\r"); // Set Wi-Fi module's /CTS pin to output-high.

Parameters
commandA pointer to a string that contains a valid serial command, that has been stripped of its command start character (the default is 254). The string terminates with a carriage return (\r).
Returns
&wifi_buf[1] The address of the first printable character in the Wi-Fi module's reply.
int wifi_connect ( char *  address,
int  port 
)

Attempt a TCP connection to address on port.

Parameters
*addressThe destination address of the target to connect to.
portThe destination address of the target to connect to.
Returns
A handle to the TCP connection (positive value), or a negative error code.
int wifi_disconnect ( int  idOrHandle)

Terminate an established connection or listener via its handle or id (respectively), freeing it to rejoin the available connection or listener pools.

Parameters
idOrHandleThe handle returned by wifi_connect or id returned by wifi_listen.
Returns
0 on success, or positive errir or a negative network code.
int wifi_ip ( int  mode,
int *  ipAddr 
)

Check the IP address for the Parallax Wi-Fi module.

Parameters
modeDetermines which Wi-Fi mode is used, either STA (staion mode IP address) or AP (access point IP address).
ipAddrA pointer to a four element int array.
Returns
status 'S' for success or 'E' for error.
int wifi_join ( char *  network,
char *  password 
)

Attempt to join a network via the ssid access point using passphrase.

Parameters
*networkThe desired access point’s SSID name.
*passwordThe desired access point’s passphrase.
Returns
0 on success, or error code (a negative value).
int wifi_leave ( int  newMode)

Leave an AP network and transition into a mode that's not pure STA. The wi-fi module will forget the current station IP address.

Parameters
newModeThe new mode after leaving a network, either STA_AP (station + access point) or AP (access point).
Returns
The new mode constant, either STA_AP (0xF2) or AP (0xF3).
int wifi_listen ( char  protocol,
char *  path 
)

Activate a listener process to monitor HTTP or WebSocket protocol activity on port 80 with a specified path.

Parameters
protocolUse HTTP (for HTTP), or WS (for WebSocket).
pathThe 'path' part of the URL that the remote client uses to access this module and its resources. The path can end in an asterisk '*' to match anything that begins with path.
Returns
wifi_id (positive if success, negative if error code).
int wifi_mode ( int  mode)

Set or check the Wi-Fi module's network mode.

Parameters
modeUse AP (access point), STA_AP (station + access point), or STA (station only). To check use CHECK.
Returns
mode, either the new or the current mode.
void wifi_poll ( int *  event,
int *  id,
int *  handle 
)

Check for activity like incoming HTTP GET/POST requests, HTTP/WebSocket/TCP connections/disconnections, and incoming WebSocket/TCP data. Example: int event, id, handle;...wifi_poll(&event, &id, &handle);.

Parameters
eventAddress of the variable to receive the event poll reports. Values that wifi_poll might place in this variable include: 'G' (GET request), 'P' (POST request), 'W' (WebSocket connection request), 'D' (data ready), 'S' (success of a reply or send operation), 'X' (disconnect occurred), 'N' (nothing to report), and 'E' (error). For more information on these codes and their meanings, see the POLL command section in the Parallax Wi-Fi Module Firmware Guide. You can find it in the Downloads section of the Wi-Fi module's product page (search for 32420) at www.parallax.com.
idThe identifier of the listener that matched the request.
handleThe connection identifier to use for this request.
int wifi_print ( int  protocol,
int  handle,
const char *  fmt,
  ... 
)

The Wi-Fi module version of the simpletext library's print function. It simplifies formatting data in strings that can be: Responses to GET requests, WebSocket data transmitted, serial commands to the Wi-Fi module, and outgoing TCP messages. This function can be called to send unsolicited data to a WebSocket, a serial command to a Wi-Fi module, or for transmitting a TCP string. It can also be called to reply to an HTTP GET request, which is indicated by wifi_poll storing 'G' in the event variable.

This function has lots of usage examples in the /Examples/Propeller C subfolder of parallax-esp-2016-11-02-1804b and newer. The zip file with this folder is in the downloads section of the Parallax Wi-Fi Module page at www.parallax.com (search 32420).

Parameters
protocolGET (response to incoming HTTP GET request), WS (outgoing WebSocket data), CMD (command string + data sent to module), or TCP, (TCP data send).
handleThe handle value from the most recent wifi_poll call.
*fmtA subset of format strings available in the print function. Supported: "%b" (binary), "%c" (character), "%d" (integer), "%f" (32-bit floating point), "%s" (string) and "%x" (hexadecimal). Many of the length and precision modifiers are also supported, like "%6.2f", which will result in six digits and two digits of precision. Note, in v0.80, if the protocol is TCP, only one "%s" is supported. After updates to the simpletext library, this will likely support more options.
...The argument list, typically pointers to the variables that correspond to format string elements.
Returns
blocks The number of blocks scanned.
int wifi_recv ( int  handle,
char *  data,
int  size 
)

Retrieve incoming HTTP body or WebSocket/TCP data.

Parameters
handleAn active connection handle; returned by CONNECT or POLL.
*dataAddress of the character array to receive the response.
sizeThe maximum number of bytes to receive.
Returns
number of bytes received.
int wifi_replyStringCopy ( char *  targetStr)

Copy a reply from the libwifi response buffer to a character array.

Parameters
*targetStrThe address of the array that will receive a copy of the response buffer.
Returns
int wifi_scan ( int  protocol,
int  handle,
const char *  fmt,
  ... 
)

The Wi-Fi module version of the simpletext library's scan function. It simplifies extracting data contained in strings from incoming POST requests, WebSocket data, responses to commands, and TCP messages. This Function can be called after the wifi_poll function has sent event information that an incoming request//response/message is ready for the Propeller to receive. This command has a variety of usage examples in the /Examples/Propeller C subfolder of parallax-esp-2016-11-02-1804b and newer. The zip file with this folder is in the downloads section of the Parallax Wi-Fi Module page at www.parallax.com (search 32420).

Parameters
protocolPOST (incoming HTTP POST request), WS (incoming WebSocket data), CMD (incoming reply to a command that was issued with wifi_print), or TCP, incoming TCP data.
handleThe handle value from the most recent wifi_poll call.
*fmtA subset of format strings available in the scan function. Supported: "%b" (binary), "%c" (character), "%d" (integer), "%f" (32-bit floating point), "%s" (string) and "%x" (hexadecimal). For POST requests, the name in the name/value pair should be prepended. For example, note the io in wifi_scan(POST, handle, "io%d%d", &pin, &state); Note, in v0.80, if the protocol is TCP, only one "%s" is supported. After updates to the simpletext library, this will likely support more options.
...The argument list, typically pointers to the variables that correspond to format string elements. Use "&variable" for char, int, and float or arrayName (without the ampersand) for arrays.
Returns
blocks The number of blocks scanned.
char wifi_send ( int  handle,
char *  data,
int  size 
)

Transmit WebSocket/TCP data, or extended HTTP body (after REPLY command).

Parameters
handleAn active connection handle; returned by CONNECT or POLL.
dataA zero terminated string (character array or string constant) that contains the data.
sizeThe number of bytes of data in this transmission.
Returns
Number of bytes sent.
void wifi_setBuffer ( char *  buffer,
int  size 
)

Sets the Wi-Fi buffer to an user declared external character array.

Parameters
bufferA pointer to the buffer that will store the commands and data transmitted to the Wi-Fi module and its replies.
sizeNumber of bytes in the buffer.
fdserial* wifi_start ( int  fromDO,
int  toDI,
int  baud,
int  comSelect 
)

Set up Wi-Fi module serial connections for data command and transparent data communication.

Parameters
fromDONumber of Propeller I/O pin that will receive signals from the Wi-Fi module's DO pin.
toDINumber of Propeller I/O pin that will transmit signals to the Wi-Fi module's DI pin.
baudCommunication baud rate (default 115200).
comSelectDefines which lines transmit and receive terminal data. Options:
  • WX_ALL_COM - All programming, terminal and Wi-Fi application communication is routed through the WX Wi-Fi module on a Propeller Activity Board WX. SEL must be set high, and DO and DI should be left floating. IPMORTANT: 31 and 30 are the only toDI and fromDO arguments that should be used with this mode. Example: wifi_start(31, 30, 115200, WX_ALL_COM)
  • USB_PGM_TERM - Programming and terminal data through USB. Wi- Fi application communication is routed from selected I/O pins through the Activity Board's DI and DO sockets. SEL must be pulled low. Example: wifi_start(10, 9, 115200, USB_PGM_TERM);
  • USB_PGM - Programming through USB but terminal and Wi-Fi app communication goes through the WX Wi-Fi Module using the Activity Board's DO and DI sockets. Pull SEL low, during programming only. Example: wifi_start(10, 9, 115200, USB_PGM);
  • Values 0..31 - I/O pin controlled switching between USB terminal and WX Wi-Fi app communication. SEL should be connected to an I/O pin, and also pulled low if programmed through USB, or high if programmed through WX Wi-Fi. Leave Activity Board DO and DI floating. NOTE: Programming over Wi-Fi is only for Activity Board WX. If your Activity Board is not WX, only load programs through USB with SEL pulled down. Example: wifi_start(31, 30, 115200, 8);
Returns
*wifi_fds - The full duplex serial connection ID.