![]() |
Wi-Fi Module WX library
v0.82
Collection of convenience functions for the Parallax WX Wi-Fi Module
|
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. More... | |
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. More... | |
int | wifi_connect (char *address, int port) |
Attempt a TCP connection to address on port. More... | |
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. More... | |
int | wifi_ip (int mode, int *ipAddr) |
Check the IP address for the Parallax Wi-Fi module. More... | |
int | wifi_join (char *network, char *password) |
Attempt to join a network via the ssid access point using passphrase. More... | |
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. More... | |
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. More... | |
int | wifi_mode (int mode) |
Set or check the Wi-Fi module's network mode. More... | |
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);. More... | |
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. More... | |
int | wifi_recv (int handle, char *data, int size) |
Retrieve incoming HTTP body or WebSocket/TCP data. More... | |
int | wifi_replyStringCopy (char *targetStr) |
Copy a reply from the libwifi response buffer to a character array. More... | |
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). More... | |
char | wifi_send (int handle, char *data, int size) |
Transmit WebSocket/TCP data, or extended HTTP body (after REPLY command). More... | |
void | wifi_setBuffer (char *buffer, int size) |
Sets the Wi-Fi buffer to an user declared external character array. More... | |
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. More... | |
void | wifi_stop (void) |
Stops the process started by wifi_start and recovers any memory that was allocated for command/reply storage and parsing. | |
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.
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.
#define USB_PGM -3 |
#define USB_PGM_TERM -2 |
#define WX_ALL_COM -1 |
char* wifi_bufferSize | ( | int | bytes | ) |
Sets the size (in bytes) of the Wi-Fi communication buffer.
bytes | Number of bytes the buffer should be. |
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.
command | A 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). |
int wifi_connect | ( | char * | address, |
int | port | ||
) |
Attempt a TCP connection to address on port.
*address | The destination address of the target to connect to. |
port | The destination address of the target to connect to. |
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.
idOrHandle | The handle returned by wifi_connect or id returned by wifi_listen. |
int wifi_ip | ( | int | mode, |
int * | ipAddr | ||
) |
Check the IP address for the Parallax Wi-Fi module.
mode | Determines which Wi-Fi mode is used, either STA (staion mode IP address) or AP (access point IP address). |
ipAddr | A pointer to a four element int array. |
int wifi_join | ( | char * | network, |
char * | password | ||
) |
Attempt to join a network via the ssid access point using passphrase.
*network | The desired access point’s SSID name. |
*password | The desired access point’s 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.
newMode | The new mode after leaving a network, either STA_AP (station + access point) or AP (access point). |
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.
protocol | Use HTTP (for HTTP), or WS (for WebSocket). |
path | The '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. |
int wifi_mode | ( | int | mode | ) |
Set or check the Wi-Fi module's network mode.
mode | Use AP (access point), STA_AP (station + access point), or STA (station only). To check use CHECK. |
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);.
event | Address 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. |
id | The identifier of the listener that matched the request. |
handle | The 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).
protocol | GET (response to incoming HTTP GET request), WS (outgoing WebSocket data), CMD (command string + data sent to module), or TCP, (TCP data send). |
handle | The handle value from the most recent wifi_poll call. |
*fmt | A 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. |
int wifi_recv | ( | int | handle, |
char * | data, | ||
int | size | ||
) |
Retrieve incoming HTTP body or WebSocket/TCP data.
handle | An active connection handle; returned by CONNECT or POLL. |
*data | Address of the character array to receive the response. |
size | The maximum number of bytes to receive. |
int wifi_replyStringCopy | ( | char * | targetStr | ) |
Copy a reply from the libwifi response buffer to a character array.
*targetStr | The address of the array that will receive a copy of the response buffer. |
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).
protocol | POST (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. |
handle | The handle value from the most recent wifi_poll call. |
*fmt | A 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.82, if the protocol is TCP, only one "%s" is supported. Also for TCP, it must only use the string created and passed to wifi_setBuffer during initialization. See ...Documents from OpenWeatherMap.side for an example. |
... | 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. |
char wifi_send | ( | int | handle, |
char * | data, | ||
int | size | ||
) |
Transmit WebSocket/TCP data, or extended HTTP body (after REPLY command).
handle | An active connection handle; returned by CONNECT or POLL. |
data | A zero terminated string (character array or string constant) that contains the data. |
size | The number of bytes of data in this transmission. |
void wifi_setBuffer | ( | char * | buffer, |
int | size | ||
) |
Sets the Wi-Fi buffer to an user declared external character array.
buffer | A pointer to the buffer that will store the commands and data transmitted to the Wi-Fi module and its replies. |
size | Number 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.
fromDO | Number of Propeller I/O pin that will receive signals from the Wi-Fi module's DO pin. |
toDI | Number of Propeller I/O pin that will transmit signals to the Wi-Fi module's DI pin. |
baud | Communication baud rate (default 115200). |
comSelect | Defines which lines transmit and receive terminal data. Options: |