MegaWiFi API implementation. More...

Modules
	mw_ctrl_pins
	Pins used to control WiFi module.

Data Structures
struct	mw_ap_data
	Access Point data. More...

Macros
#define	MW_API_VERSION_MAJOR 1
	API version implemented, major number. More...

#define	MW_API_VERSION_MINOR 5
	API version implemented, minor number. More...

#define	MW_COMMAND_TOUT_MS 1000
	Timeout for standard commands in milliseconds. More...

#define	MW_CONNECT_TOUT_MS 10000
	Timeout for TCP connections. More...

#define	MW_HTTP_OPEN_TOUT_MS 10000
	Timeout for HTTP open command in milliseconds. More...

#define	MW_SCAN_TOUT_MS 10000
	Timeout for the AP scan command in milliseconds. More...

#define	MW_ASSOC_TOUT_MS 20000
	Timeout for the AP associate command in milliseconds. More...

#define	MW_ASSOC_WAIT_SLEEP_MS 5000
	Time to sleep before waiting for assoc in milliseconds. More...

#define	MW_UPGRADE_TOUT_MS 180000
	Timeout for upgrade command in milliseconds. More...

#define	MW_STAT_POLL_MS 250
	Milliseconds between status polls while in wm_ap_assoc_wait() More...

#define	MW_SSID_MAXLEN 32
	Maximum SSID length (including '\0'). More...

#define	MW_PASS_MAXLEN 64
	Maximum password length (including '\0'). More...

#define	MW_NTP_POOL_MAXLEN 80
	Maximum length of an NTP pool URI (including '\0'). More...

#define	MW_NUM_CFG_SLOTS 3
	Number of AP configurations stored to nvflash. More...

#define	MW_NUM_DNS_SERVERS 2
	Number of DSN servers supported per AP configuration. More...

#define	MW_FSM_QUEUE_LEN 8
	Length of the FSM queue. More...

#define	MW_MAX_SOCK 3
	Maximum number of simultaneous TCP connections. More...

#define	MW_CTRL_CH 0
	Control channel used for LSD protocol. More...

#define	MW_HTTP_CH LSD_MAX_CH - 1
	Channel used for HTTP requests and cert sets. More...

#define	MW_CMD_MIN_BUFLEN 168

#define	mw_tcp_disconnect(ch) mw_close(ch)
	Closes a TCP socket. This is an alias of mw_close(). More...

#define	mw_udp_unset(ch) mw_close(ch)
	Frees a UDP socket. This is an alias of mw_close(). More...

#define	mw_module_reset() do{uart_set_bits(MCR, MW__RESET);}while(0)
	Puts the WiFi module in reset state. More...

#define	mw_module_start() do{uart_clr_bits(MCR, MW__RESET);}while(0)
	Releases the module from reset state. More...

Enumerations
enum	mw_err
	Error codes for MegaWiFi API functions. More...

enum	mw_http_method
	Supported HTTP methods. More...

enum	mw_if_type
	Interface type for the mw_bssid_get() function. More...

Functions
int16_t	mw_init (char *cmd_buf, uint16_t buf_len)
	Module initialization. Must be called once before using any other function. It also initializes de UART. More...

static void	mw_process (void)
	Processes sends/receives pending data. More...

void	mw_cmd_data_cb_set (lsd_recv_cb cmd_recv_cb)
	Sets the callback function to be run when network data is received while waiting for a command reply. More...

enum mw_err	mw_detect (uint8_t major, uint8_t minor, char **variant)
	Performs the startup sequence for the WiFi module, and tries detecting it by requesting the version data. More...

enum mw_err	mw_version_get (uint8_t version[3], char **variant)
	Obtain module version numbers and string. More...

uint8_t *	mw_bssid_get (enum mw_if_type interface_type)
	Gets the module BSSID (the MAC address) for the specified interface. More...

enum mw_err	mw_default_cfg_set (void)
	Set default module configuration (AKA factory settings). More...

enum mw_err	mw_ap_cfg_set (uint8_t slot, const char ssid, const char pass, enum mw_phy_type phy_type)
	Set access point configuration (SSID and password). More...

enum mw_err	mw_ap_cfg_get (uint8_t slot, char ssid, char pass, enum mw_phy_type *phy_type)
	Gets access point configuration (SSID and password). More...

enum mw_err	mw_ip_cfg_set (uint8_t slot, const struct mw_ip_cfg *ip)
	Set IPv4 configuration. More...

enum mw_err	mw_ip_cfg_get (uint8_t slot, struct mw_ip_cfg **ip)
	Get IPv4 configuration. More...

enum mw_err	mw_wifi_adv_cfg_set (const struct mw_wifi_adv_cfg *wifi)
	Set advanced WiFi configuration. More...

struct mw_wifi_adv_cfg *	mw_wifi_adv_cfg_get (void)
	Get advanced WiFi configuration. More...

enum mw_err	mw_cfg_save (void)
	Saves changed configuration parameters to non-volatile memory. More...

enum mw_err	mw_ip_current (struct mw_ip_cfg **ip)
	Get current IP configuration, of the joined AP. More...

int16_t	mw_ap_scan (enum mw_phy_type phy_type, char *ap_data, uint8_t aps)
	Scan for access points. More...

int16_t	mw_ap_fill_next (const char ap_data, uint16_t pos, struct mw_ap_data apd, uint16_t data_len)
	Parses received AP data and fills information of the AP at "pos". Useful to extract AP information from the data obtained by calling mw_ap_scan() function. More...

enum mw_err	mw_ap_assoc (uint8_t slot)
	Tries associating to an AP. If successful, also configures IPv4. More...

enum mw_err	mw_ap_assoc_wait (int16_t tout_frames)
	Polls the module status until it reports device is associated to AP or timeout occurs. More...

enum mw_err	mw_def_ap_cfg (uint8_t slot)
	Sets default AP/IP configuration. More...

enum mw_err	mw_ap_disassoc (void)
	Dissasociates from a previously associated AP. More...

int16_t	mw_def_ap_cfg_get (void)
	Gets default AP/IP configuration slot. More...

enum mw_err	mw_tcp_connect (uint8_t ch, const char dst_addr, const char dst_port, const char *src_port)
	Tries establishing a TCP connection with specified server. More...

enum mw_err	mw_close (uint8_t ch)
	Closes and disconnects a socket from specified channel. More...

enum mw_err	mw_udp_set (uint8_t ch, const char dst_addr, const char dst_port, const char *src_port)
	Configures a UDP socket to send/receive data. More...

enum mw_err	mw_tcp_bind (uint8_t ch, uint16_t port)
	Binds a socket to a port, and listens to connections on the port. If a connection request is received, it will be automatically accepted. More...

enum mw_err	mw_sock_conn_wait (uint8_t ch, int16_t tout_frames)
	Polls a socket until it is ready to transfer data. Typical use of this function is after a successful mw_tcp_bind(). More...

static enum lsd_status	mw_recv (char buf, int16_t len, void ctx, lsd_recv_cb recv_cb)
	Receive data, asyncrhonous interface. More...

static enum lsd_status	mw_udp_reuse_recv (struct mw_reuse_payload data, int16_t len, void ctx, lsd_recv_cb recv_cb)
	Receive data using an UDP socket in reuse mode. More...

static enum lsd_status	mw_udp_reuse_send (uint8_t ch, const struct mw_reuse_payload data, int16_t len, void ctx, lsd_send_cb send_cb)
	Send data using a UDP socket in reuse mode. More...

static enum lsd_status	mw_send (uint8_t ch, const char data, int16_t len, void ctx, lsd_send_cb send_cb)
	Sends data through a socket, using a previously allocated channel. Asynchronous interface. More...

enum mw_err	mw_recv_sync (uint8_t ch, char buf, int16_t *buf_len, int16_t tout_frames)
	Receive data, syncrhonous interface. More...

enum mw_err	mw_send_sync (uint8_t ch, const char *data, uint16_t len, int16_t tout_frames)
	Sends data through a socket, using a previously allocated channel. Synchronous interface. More...

union mw_msg_sys_stat *	mw_sys_stat_get (void)
	Get system status. More...

enum mw_sock_stat	mw_sock_stat_get (uint8_t ch)
	Get socket status. More...

enum mw_err	mw_sntp_cfg_set (const char tz_str, const char server[3])
	Configure SNTP parameters and timezone. More...

enum mw_err	mw_sntp_cfg_get (char *tz_str, char server[3])
	Get SNTP parameters and timezone configuration. More...

char *	mw_date_time_get (uint32_t dt_bin[2])
	Get date and time. More...

enum mw_err	mw_flash_id_get (uint8_t man_id, uint16_t dev_id)
	Get the identifiers of the flash chip in the WiFi module. More...

enum mw_err	mw_flash_sector_erase (uint16_t sect)
	Erase a 4 KiB Flash sector. Every byte of an erased sector will be read as 0xFF. More...

enum mw_err	mw_flash_write (uint32_t addr, uint8_t *data, uint16_t data_len)
	Write data to specified flash address. More...

uint8_t *	mw_flash_read (uint32_t addr, uint16_t data_len)
	Read data from specified flash address. More...

enum mw_err	mw_gamertag_set (uint8_t slot, const struct mw_gamertag *gamertag)
	Set gamertag information for one slot. More...

struct mw_gamertag *	mw_gamertag_get (uint8_t slot)
	Get gamertag information for one slot. More...

enum mw_err	mw_log (const char *msg)
	Write a message to the WiFi module log trace. More...

enum mw_err	mw_factory_settings (void)
	Set factory default configuration. More...

void	mw_power_off (void)
	Powers off the WiFi module. More...

void	mw_sleep (int16_t frames)
	Sleep the specified amount of frames. More...

enum mw_err	mw_http_url_set (const char *url)
	Set URL for HTTP requests. More...

enum mw_err	mw_http_method_set (enum mw_http_method method)
	Set method for HTTP requests. More...

enum mw_err	mw_http_header_add (const char key, const char value)
	Add an HTTP header. More...

enum mw_err	mw_http_header_del (const char *key)
	Delete a previously added HTTP header. More...

enum mw_err	mw_http_open (uint32_t content_len)
	Open HTTP connection. More...

int16_t	mw_http_finish (uint32_t *content_len, int16_t tout_frames)
	Finish an opened HTTP request. More...

uint32_t	mw_http_cert_query (void)
	Query the X.509 hash of the installed PEM certificate. More...

enum mw_err	mw_http_cert_set (uint32_t cert_hash, const char *cert, uint16_t cert_len)
	Set the PEM certificate to use on HTTPS requests. More...

int16_t	mw_http_cleanup (void)
	Clean-up an HTTP request, freeing associated resources. More...

char *	mw_def_server_get (void)
	Get the default server used for MegaWiFi connections. More...

enum mw_err	mw_def_server_set (const char *server_url)
	Set the default server used for MegaWiFi connections. More...

uint8_t *	mw_hrng_get (uint16_t rnd_len)
	Get random numbers. More...

enum mw_err	mw_ga_endpoint_set (const char endpoint, const char priv_key)
	Set endpoint for Game API. More...

enum mw_err	mw_ga_key_value_add (const char key, const char value, uint16_t num_pairs)
	Add parameters to the Game API request in key/value format. More...

int16_t	mw_ga_request (enum mw_http_method method, const char path, uint8_t num_paths, const char key, const char *value, uint8_t num_kv_pairs, uint32_t content_len, int16_t tout_frames)
	Perform a GameAPI request, with the previously set endpoint and key/value pairs. More...

enum mw_err	mw_fw_upgrade (const char *name)
	Over-The-Air upgrade WiFi module firmware. More...

static enum lsd_status	mw_cmd_send (mw_cmd cmd, void ctx, lsd_send_cb send_cb)
	Send a command to the WiFi module. More...

static enum lsd_status	mw_cmd_recv (mw_cmd rep, void ctx, lsd_recv_cb recv_cb)
	Try obtaining a reply to a command. More...

Detailed Description

MegaWiFi API implementation.

API to communicate with the wifi module and the Internet. API calls are documented and most of them are self explanatory. Mostly the only weird thing about the API is UDP reuse mode. If you enable reuse mode (setting the dst_addr and/or dst_port to NULL in the mw_udp_set() call), received data will prepend the IP and port of the peer (using mw_reuse_payload data structure), and data to be sent also requires the IP and port to be prepended to the payload.

Author: Jesus Alonso (doragasu)

Date: 2015

Note: This module uses a loop_timer from the loop module.

Todo:: Missing a lot of integrity checks, also module should track used channels, and is not currently doing it

Macro Definition Documentation

◆ MW_API_VERSION_MAJOR

#define MW_API_VERSION_MAJOR 1

API version implemented, major number.

Definition at line 36 of file megawifi.h.

◆ MW_API_VERSION_MINOR

#define MW_API_VERSION_MINOR 5

API version implemented, minor number.

Definition at line 39 of file megawifi.h.

◆ MW_ASSOC_TOUT_MS

#define MW_ASSOC_TOUT_MS 20000

Timeout for the AP associate command in milliseconds.

Definition at line 50 of file megawifi.h.

◆ MW_ASSOC_WAIT_SLEEP_MS

#define MW_ASSOC_WAIT_SLEEP_MS 5000

Time to sleep before waiting for assoc in milliseconds.

Definition at line 52 of file megawifi.h.

◆ MW_CMD_MIN_BUFLEN

#define MW_CMD_MIN_BUFLEN 168

Minimum command buffer length to be able to send all available commands with minimum data payload. This length might not guarantee that commands like mw_sntp_cfg_set() can be sent if payload length is big enough).

Definition at line 115 of file megawifi.h.

◆ MW_COMMAND_TOUT_MS

#define MW_COMMAND_TOUT_MS 1000

Timeout for standard commands in milliseconds.

Definition at line 42 of file megawifi.h.

◆ MW_CONNECT_TOUT_MS

#define MW_CONNECT_TOUT_MS 10000

Timeout for TCP connections.

Definition at line 44 of file megawifi.h.

◆ MW_CTRL_CH

#define MW_CTRL_CH 0

Control channel used for LSD protocol.

Definition at line 108 of file megawifi.h.

◆ MW_FSM_QUEUE_LEN

#define MW_FSM_QUEUE_LEN 8

Length of the FSM queue.

Definition at line 104 of file megawifi.h.

◆ MW_HTTP_CH

#define MW_HTTP_CH LSD_MAX_CH - 1

Channel used for HTTP requests and cert sets.

Definition at line 110 of file megawifi.h.

◆ MW_HTTP_OPEN_TOUT_MS

#define MW_HTTP_OPEN_TOUT_MS 10000

Timeout for HTTP open command in milliseconds.

Definition at line 46 of file megawifi.h.

◆ MW_MAX_SOCK

#define MW_MAX_SOCK 3

Maximum number of simultaneous TCP connections.

Definition at line 106 of file megawifi.h.

◆ mw_module_reset

#define mw_module_reset ( ) do{uart_set_bits(MCR, MW__RESET);}while(0)

Puts the WiFi module in reset state.

Definition at line 664 of file megawifi.h.

◆ mw_module_start

#define mw_module_start ( ) do{uart_clr_bits(MCR, MW__RESET);}while(0)

Releases the module from reset state.

Definition at line 669 of file megawifi.h.

◆ MW_NTP_POOL_MAXLEN

#define MW_NTP_POOL_MAXLEN 80

Maximum length of an NTP pool URI (including '\0').

Definition at line 98 of file megawifi.h.

◆ MW_NUM_CFG_SLOTS

#define MW_NUM_CFG_SLOTS 3

Number of AP configurations stored to nvflash.

Definition at line 100 of file megawifi.h.

◆ MW_NUM_DNS_SERVERS

#define MW_NUM_DNS_SERVERS 2

Number of DSN servers supported per AP configuration.

Definition at line 102 of file megawifi.h.

◆ MW_PASS_MAXLEN

#define MW_PASS_MAXLEN 64

Maximum password length (including '\0').

Definition at line 96 of file megawifi.h.

◆ MW_SCAN_TOUT_MS

#define MW_SCAN_TOUT_MS 10000

Timeout for the AP scan command in milliseconds.

Definition at line 48 of file megawifi.h.

◆ MW_SSID_MAXLEN

#define MW_SSID_MAXLEN 32

Maximum SSID length (including '\0').

Definition at line 94 of file megawifi.h.

◆ MW_STAT_POLL_MS

#define MW_STAT_POLL_MS 250

Milliseconds between status polls while in wm_ap_assoc_wait()

Definition at line 56 of file megawifi.h.

◆ mw_tcp_disconnect

#define mw_tcp_disconnect ( ch ) mw_close(ch)

Closes a TCP socket. This is an alias of mw_close().

Definition at line 412 of file megawifi.h.

◆ mw_udp_unset

#define mw_udp_unset ( ch ) mw_close(ch)

Frees a UDP socket. This is an alias of mw_close().

Definition at line 430 of file megawifi.h.

◆ MW_UPGRADE_TOUT_MS

#define MW_UPGRADE_TOUT_MS 180000

Timeout for upgrade command in milliseconds.

Definition at line 54 of file megawifi.h.

Enumeration Type Documentation

◆ mw_err

enum mw_err

Error codes for MegaWiFi API functions.

Enumerator
MW_ERR_NONE	No error (success)
MW_ERR	General error.
MW_ERR_NOT_READY	Not ready to run command.
MW_ERR_BUFFER_TOO_SHORT	Command buffer is too small.
MW_ERR_PARAM	Input parameter out of range.
MW_ERR_SEND	Error sending data.
MW_ERR_RECV	Error receiving data.

Definition at line 59 of file megawifi.h.

◆ mw_http_method

enum mw_http_method

Supported HTTP methods.

Enumerator
MW_HTTP_METHOD_GET	HTTP GET Method.
MW_HTTP_METHOD_POST	HTTP POST Method.
MW_HTTP_METHOD_PUT	HTTP PUT Method.
MW_HTTP_METHOD_PATCH	HTTP PATCH Method.
MW_HTTP_METHOD_DELETE	HTTP DELETE Method.
MW_HTTP_METHOD_HEAD	HTTP HEAD Method.
MW_HTTP_METHOD_NOTIFY	HTTP NOTIFY Method.
MW_HTTP_METHOD_SUBSCRIBE	HTTP SUBSCRIBE Method.
MW_HTTP_METHOD_UNSUBSCRIBE	HTTP UNSUBSCRIBE.
MW_HTTP_METHOD_OPTIONS	HTTP OPTIONS.

Definition at line 70 of file megawifi.h.

◆ mw_if_type

enum mw_if_type

Interface type for the mw_bssid_get() function.

Enumerator
MW_IF_STATION	Station interface.
MW_IF_SOFTAP	Access Point interface.
MW_IF_MAX	Number of supported interface types.

Definition at line 127 of file megawifi.h.

Function Documentation

◆ mw_ap_assoc()

enum mw_err mw_ap_assoc ( uint8_t slot )

Tries associating to an AP. If successful, also configures IPv4.

Parameters

[in] slot Configuration slot to use.

Returns: MW_ERR_NONE if AP join operation has been successfully started,

◆ mw_ap_assoc_wait()

enum mw_err mw_ap_assoc_wait ( int16_t tout_frames )

Polls the module status until it reports device is associated to AP or timeout occurs.

Parameters

[in] tout_frames Maximun number of frames to wait for association. Set to TSK_PEND_FOREVER for an infinite wait.

Returns: MW_ERR_NONE if device is associated to AP. MW_ERR_NOT_READY if the timeout has expired.

◆ mw_ap_cfg_get()

enum mw_err mw_ap_cfg_get	(	uint8_t	slot,
		char **	ssid,
		char **	pass,
		enum mw_phy_type *	phy_type
	)

Gets access point configuration (SSID and password).

Parameters

[in]	slot	Configuration slot to use.
[out]	ssid	String with the AP SSID got.
[out]	pass	String with the AP SSID got.
[out]	phy_type	Bitmask with the PHY type configuration.

Returns: MW_ERR_NONE on success, other code on failure.

Warning: ssid is zero padded up to 32 bytes, and pass is zero padded up to 64 bytes. If ssid is 32 bytes, it will NOT be NULL terminated. Also if pass is 64 bytes, it will NOT be NULL terminated.

◆ mw_ap_cfg_set()

enum mw_err mw_ap_cfg_set	(	uint8_t	slot,
		const char *	ssid,
		const char *	pass,
		enum mw_phy_type	phy_type
	)

Set access point configuration (SSID and password).

Parameters

[in]	slot	Configuration slot to use.
[in]	ssid	String with the AP SSID to set.
[in]	pass	String with the AP SSID to set.
[in]	phy_type	Bitmask with the PHY type configuration.

Returns: MW_ERR_NONE on success, other code on failure.

Note: Strings must be NULL terminated. Maximum SSID length is 32 bytes, maximum pass length is 64 bytes.; After a successful invocation, call mw_cfg_save() for changes to be persistent

◆ mw_ap_disassoc()

enum mw_err mw_ap_disassoc ( void )

Dissasociates from a previously associated AP.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_ap_fill_next()

int16_t mw_ap_fill_next	(	const char *	ap_data,
		uint16_t	pos,
		struct mw_ap_data *	apd,
		uint16_t	data_len
	)

Parses received AP data and fills information of the AP at "pos". Useful to extract AP information from the data obtained by calling mw_ap_scan() function.

Parameters

[in]	ap_data	Access point data obtained from mw_ap_scan().
[in]	pos	Position at which to extract data.
[out]	apd	Pointer to the extracted data from an AP.
[in]	data_len	Lenght of apData.

Returns: Position of the next AP entry in apData, 0 if no more APs available or MW_ERROR if ap data/pos combination is not valid.

Note: This functions executes locally, does not communicate with the WiFi module.

◆ mw_ap_scan()

int16_t mw_ap_scan	(	enum mw_phy_type	phy_type,
		char **	ap_data,
		uint8_t *	aps
	)

Scan for access points.

Parameters

[in]	phy_type	Bitmask with the PHY type configuration.
[out]	ap_data	Data of the found access points. Each entry has the format specified on the mw_ap_data structure.
[out]	aps	Number of found access points.

Returns: Length in bytes of the output data if operation completes successfully, or -1 if scan fails.

◆ mw_bssid_get()

uint8_t * mw_bssid_get ( enum mw_if_type interface_type )

Gets the module BSSID (the MAC address) for the specified interface.

Parameters

[in] interface_type Type of the interface to obtain BSSID from.

Returns: The requested BSSID (6 byte binary data), or NULL on error.

◆ mw_cfg_save()

enum mw_err mw_cfg_save ( void )

Saves changed configuration parameters to non-volatile memory.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_close()

enum mw_err mw_close ( uint8_t ch )

Closes and disconnects a socket from specified channel.

This function can be used to free the channel associated to both TCP and UDP sockets.

Parameters

[in] ch Channel associated to the socket to disconnect.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_cmd_data_cb_set()

void mw_cmd_data_cb_set ( lsd_recv_cb cmd_recv_cb )

Sets the callback function to be run when network data is received while waiting for a command reply.

Parameters

[in] cmd_recv_cb Callback to be run when data is received while waiting for a command reply.

Warning: If this callback is not set, data received while waiting for a command reply will be silently discarded.

◆ mw_cmd_recv()

static enum lsd_status mw_cmd_recv	(	mw_cmd *	rep,
		void *	ctx,
		lsd_recv_cb	recv_cb
	)

inlinestatic

Try obtaining a reply to a command.

Parameters

[in]	rep	Buffer to hold the command reply.
[in]	ctx	Context for the reception callback.
[in]	recv_cb	Callback for data reception completion.

Returns: Status of the reception procedure.

Definition at line 968 of file megawifi.h.

◆ mw_cmd_send()

static enum lsd_status mw_cmd_send	(	mw_cmd *	cmd,
		void *	ctx,
		lsd_send_cb	send_cb
	)

inlinestatic

Send a command to the WiFi module.

Parameters

[in]	cmd	Pointer to the filled mw_cmd command structure.
[in]	ctx	Context for callback function.
[in]	send_cb	Callback for the send operation completion.

Returns: Status of the send procedure.

Definition at line 951 of file megawifi.h.

◆ mw_date_time_get()

char * mw_date_time_get ( uint32_t dt_bin[2] )

Get date and time.

Parameters

[out] dt_bin Date and time in seconds since Epoch. If set to NULL, this info is not filled (but return value will still be properly set).

Returns: A string with the date and time in textual format, e.g.: "Thu Mar 3 12:26:51 2016", or NULL if error.

◆ mw_def_ap_cfg()

enum mw_err mw_def_ap_cfg ( uint8_t slot )

Sets default AP/IP configuration.

Parameters

[in] slot Configuration slot to use.

Returns: MW_ERR_NONE on success, other code on failure.

Note: After a successful invocation, call mw_cfg_save() for changes to be persistent

◆ mw_def_ap_cfg_get()

int16_t mw_def_ap_cfg_get ( void )

Gets default AP/IP configuration slot.

Returns: The default configuration slot, of -1 on error.

◆ mw_def_server_get()

char * mw_def_server_get ( void )

Get the default server used for MegaWiFi connections.

Returns: The server URL string, or NULL on error.

◆ mw_def_server_set()

enum mw_err mw_def_server_set ( const char * server_url )

Set the default server used for MegaWiFi connections.

Parameters

[in] server_url The server URL to set.

Returns: MW_ERR_NONE on success, other code on failure.

Note: After a successful invocation, call mw_cfg_save() for changes to be persistent

◆ mw_default_cfg_set()

enum mw_err mw_default_cfg_set ( void )

Set default module configuration (AKA factory settings).

Returns: MW_ERR_NONE on success, other code on failure.

Note: For this command to take effect, it must be followed by a module reset.

◆ mw_detect()

enum mw_err mw_detect	(	uint8_t *	major,
		uint8_t *	minor,
		char **	variant
	)

Performs the startup sequence for the WiFi module, and tries detecting it by requesting the version data.

Parameters

[out]	major	Major version number.
[out]	minor	Minor version number.
[out]	variant	String with firmware variant ("std" for standard).

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_factory_settings()

enum mw_err mw_factory_settings ( void )

Set factory default configuration.

Returns: MW_ERR_NONE on success, other code on failure.

Note: It is recommended to reboot the module after this command.

◆ mw_flash_id_get()

enum mw_err mw_flash_id_get	(	uint8_t *	man_id,
		uint16_t *	dev_id
	)

Get the identifiers of the flash chip in the WiFi module.

Parameters

[out]	man_id	ID of the flash chip manufacturer.
[out]	dev_id	Device IDs of the flash chip.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_flash_read()

uint8_t * mw_flash_read	(	uint32_t	addr,
		uint16_t	data_len
	)

Read data from specified flash address.

Parameters

[in]	addr	Address from which data will be read.
[in]	data_len	Number of bytes to read from addr.

Returns: Pointer to read data on success, or NULL if command failed.

◆ mw_flash_sector_erase()

enum mw_err mw_flash_sector_erase ( uint16_t sect )

Erase a 4 KiB Flash sector. Every byte of an erased sector will be read as 0xFF.

Parameters

[in] sect Sector number to erase.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_flash_write()

enum mw_err mw_flash_write	(	uint32_t	addr,
		uint8_t *	data,
		uint16_t	data_len
	)

Write data to specified flash address.

Parameters

[in]	addr	Address to which data will be written.
[in]	data	Data to be written to flash chip.
[in]	data_len	Length in bytes of data field.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_fw_upgrade()

enum mw_err mw_fw_upgrade ( const char * name )

Over-The-Air upgrade WiFi module firmware.

Parameters

[in] name Name of the firmware blob to upgrade. E.g. "mw_rtos_std_v1.4.1"

Returns: Status of the send procedure.

◆ mw_ga_endpoint_set()

enum mw_err mw_ga_endpoint_set	(	const char *	endpoint,
		const char *	priv_key
	)

Set endpoint for Game API.

Example endpoint for GameJolt: "https://api.gamejolt.com/api/game/v1_2/".

Parameters

[in]	endpoint	Endpoint for the Game API to set.
[in]	priv_key	Private key used for request signatures.

Returns: MW_ERR_NONE on success, other code on failure.

Note: The endpoint set persists between successive mw_ga_request() calls.

◆ mw_ga_key_value_add()

enum mw_err mw_ga_key_value_add	(	const char **	key,
		const char **	value,
		uint16_t	num_pairs
	)

Add parameters to the Game API request in key/value format.

Example key:value pair for GameJolt: "game_id":"123456".

Parameters

[in]	key	Array with the keys to add.
[in]	value	Array with the values to add
[in]	num_pairs	Number of key/value pairs to add.

Returns: MW_ERR_NONE on success, other code on failure.

Note: The key/value pairs set persist between successive mw_ga_request() calls.; Call mw_ga_key_value_add(NULL, NULL, 0) to clear previously set key/value pairs.; Key/value pairs must NOT be URL encoded. Encoding is handled internally.

◆ mw_ga_request()

int16_t mw_ga_request	(	enum mw_http_method	method,
		const char **	path,
		uint8_t	num_paths,
		const char **	key,
		const char **	value,
		uint8_t	num_kv_pairs,
		uint32_t *	content_len,
		int16_t	tout_frames
	)

Perform a GameAPI request, with the previously set endpoint and key/value pairs.

The request can also have URL encoded parameters. that are added to the previously set key/value pairs.

Example request for GameJolt:

method: MW_HTTP_METHOD_GET
path: "trophies"
key:value: "achieved":"true"

Parameters

[in]	method	HTTP method to use. Most likely MW_HTTP_METHOD_GET.
[in]	path	Additional paths to add to the request.
[in]	num_paths	Number of additional paths to add.
[in]	key	Additional paths to add to the request.
[in]	value	Additional paths to add to the request.
[in]	num_kv_pairs	Number of key/value pairs.
[out]	content_len	Content length of the API response.
[in]	tout_frames	Number of frames to wait before canceling the request due to a timeout error.

Returns: HTTP status code on success (e.g. 200), or an error (lower than 100) if the HTTP request could not be completed.

Note: Even if the HTTP request is completed, that does not mean there are no errors, if the returned status code is 4xx or 5xx, there is a client side or server side error.; path, key and value parameters must not be URL encoded. Encoding is handled internally.

◆ mw_gamertag_get()

struct mw_gamertag * mw_gamertag_get ( uint8_t slot )

Get gamertag information for one slot.

Parameters

[in] slot Slot to get gamertag from.

Returns: Gamertag information on success, NULL on error.

◆ mw_gamertag_set()

enum mw_err mw_gamertag_set	(	uint8_t	slot,
		const struct mw_gamertag *	gamertag
	)

Set gamertag information for one slot.

Parameters

[in]	slot	Slot to use (from 0 to 2).
[in]	gamertag	Gamertag information to set on specified slot.

Returns: MW_ERR_NONE on success, other code on failure.

Note: After a successful invocation, call mw_cfg_save() for changes to be persistent

◆ mw_hrng_get()

uint8_t * mw_hrng_get ( uint16_t rnd_len )

Get random numbers.

Parameters

[in] rnd_len Number of bytes of resulting random array.

Returns: The buffer with the requested random numbers on success, or NULL when error.

◆ mw_http_cert_query()

uint32_t mw_http_cert_query ( void )

Query the X.509 hash of the installed PEM certificate.

Returns: 0xFFFFFFFF if certificate is not installed or error occurs, or the installed X.509 certificate hash on success.

◆ mw_http_cert_set()

enum mw_err mw_http_cert_set	(	uint32_t	cert_hash,
		const char *	cert,
		uint16_t	cert_len
	)

Set the PEM certificate to use on HTTPS requests.

The certificate is stored on the non volatile memory of the module, and when present will be used in HTTPS requestes. This function can also be used to delete a previously saved certificate using a NULL input value.

Parameters

[in]	cert_hash	X.509 hash of the certificate to set, ignored if cert_len set to 0.
[in]	cert	PEM certificate in plain text. Ignored if cert_len set to 0. previously stored certificate.
[in]	cert_len	Certificate length in bytes. Set to 0 to delete a previously stored certificate.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_http_cleanup()

int16_t mw_http_cleanup ( void )

Clean-up an HTTP request, freeing associated resources.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_http_finish()

int16_t mw_http_finish	(	uint32_t *	content_len,
		int16_t	tout_frames
	)

Finish an opened HTTP request.

After a successful call to mw_http_open(), and sending the content (if any), call this function to receive the HTTP response headers, and obtain the length of the body to receive with a further call to mw_recv() or mw_recv_sync(), using MW_HTTP_CH.

Parameters

[out]	content_len	Length of the response content to receive after a successfull call to this function.
[in]	tout_frames	Maximun number of frames to wait for reply.

Returns: The HTTP status code if the request was completed, or an error code (lower than 100) if the HTTP request did not complete.

Note: Even if the HTTP request is completed, that does not mean there are no errors, if the returned status code is 4xx or 5xx, there is a client side or server side error.

◆ mw_http_header_add()

enum mw_err mw_http_header_add	(	const char *	key,
		const char *	value
	)

Add an HTTP header.

Parameters

[in]	key	Header key.
[in]	value	Value to set for the key.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_http_header_del()

enum mw_err mw_http_header_del ( const char * key )

Delete a previously added HTTP header.

Parameters

[in] key Key of the header to delete.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_http_method_set()

enum mw_err mw_http_method_set ( enum mw_http_method method )

Set method for HTTP requests.

Parameters

[in] method Method to set.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_http_open()

enum mw_err mw_http_open ( uint32_t content_len )

Open HTTP connection.

This functions opens the HTTP connection, sends the HTTP headers, and prepares the module to send the specified content_len if (if any) with a successive mw_send() or mw_send_sync(), using MW_HTTP_CH channel.

Parameters

[in] content_len Length of the content to write in HTTP request, after a successfull call to this function.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_http_url_set()

enum mw_err mw_http_url_set ( const char * url )

Set URL for HTTP requests.

Parameters

[in] url URL to set.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_init()

int16_t mw_init	(	char *	cmd_buf,
		uint16_t	buf_len
	)

Module initialization. Must be called once before using any other function. It also initializes de UART.

Parameters

[in]	cmd_buf	Pointer to the buffer used to send and receive commands.
[in]	buf_len	Length of cmdBuf in bytes.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_ip_cfg_get()

enum mw_err mw_ip_cfg_get	(	uint8_t	slot,
		struct mw_ip_cfg **	ip
	)

Get IPv4 configuration.

Parameters

[in]	slot	Configuration slot to use.
[out]	ip	Double pointer to mw_ip_cfg structure, with IP conf.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_ip_cfg_set()

enum mw_err mw_ip_cfg_set	(	uint8_t	slot,
		const struct mw_ip_cfg *	ip
	)

Set IPv4 configuration.

Parameters

[in]	slot	Configuration slot to use.
[in]	ip	Pointer to the mw_ip_cfg structure, with IP configuration.

Returns: MW_ERR_NONE on success, other code on failure.

Note: After a successful invocation, call mw_cfg_save() for changes to be persistent

◆ mw_ip_current()

enum mw_err mw_ip_current ( struct mw_ip_cfg ** ip )

Get current IP configuration, of the joined AP.

Parameters

[out] ip Double pointer to mw_ip_cfg structure, with IP conf.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_log()

enum mw_err mw_log ( const char * msg )

Write a message to the WiFi module log trace.

Parameters

[in] msg Message to write to the log trace.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_power_off()

void mw_power_off ( void )

Powers off the WiFi module.

The module will be put in deep sleep mode. To wake it up, the RESET pin must be toggled.

◆ mw_process()

static void mw_process ( void )

inlinestatic

Processes sends/receives pending data.

Call this function as much as possible to process incoming/outgoing data.

Warning: No data will be sent/received if this function is not frequently invoked.

Definition at line 152 of file megawifi.h.

◆ mw_recv()

static enum lsd_status mw_recv	(	char *	buf,
		int16_t	len,
		void *	ctx,
		lsd_recv_cb	recv_cb
	)

inlinestatic

Receive data, asyncrhonous interface.

Parameters

[in]	buf	Reception buffer.
[in]	len	Length of the receive buffer.
[in]	ctx	Context pointer to pass to the reception callbak.
[in]	recv_cb	Callback to run when reception is complete or errors.

Returns: Status of the receive procedure.

Definition at line 466 of file megawifi.h.

◆ mw_recv_sync()

enum mw_err mw_recv_sync	(	uint8_t *	ch,
		char *	buf,
		int16_t *	buf_len,
		int16_t	tout_frames
	)

Receive data, syncrhonous interface.

Parameters

[out]	ch	Channel on which data was received.
[out]	buf	Reception buffer.
[in,out]	buf_len	On input, length of the buffer. On output, received data length in bytes.
[in]	tout_frames	Reception timeout in frames. Set to TSK_PEND_FOREVER for infinite wait (dangerous!).

Returns: Status of the receive procedure.

Warning: Do not use more than one syncrhonous call at once. You must wait until a syncrhonous call ends to issue another one.

◆ mw_send()

static enum lsd_status mw_send	(	uint8_t	ch,
		const char *	data,
		int16_t	len,
		void *	ctx,
		lsd_send_cb	send_cb
	)

inlinestatic

Sends data through a socket, using a previously allocated channel. Asynchronous interface.

Parameters

[in]	ch	Channel used to send the data.
[in]	data	Buffer to send.
[in]	len	Length of the data to send.
[in]	ctx	Context for the send callback function.
[in]	send_cb	Callback to run when send completes or errors.

Returns: Status of the send procedure. Usually LSD_STAT_BUSY is returned, and the send procedure is then performed in background.

Note: Calling this function while there is a send procedure in progress, will cause the function call to fail with LSD_STAT_SEND_ERR_IN_PROGRESS.

Warning: For very short data frames, it is possible that the send callback is run before this function returns. In this case, the function returns LSD_STAT_COMPLETE.

Definition at line 526 of file megawifi.h.

◆ mw_send_sync()

enum mw_err mw_send_sync	(	uint8_t	ch,
		const char *	data,
		uint16_t	len,
		int16_t	tout_frames
	)

Sends data through a socket, using a previously allocated channel. Synchronous interface.

Parameters

[in]	ch	Channel used to send the data.
[in]	data	Buffer to send.
[in]	len	Length of the data to send.
[in]	tout_frames	Timeout for send operation in frames. Set to 0 for infinite wait (dangerous!).

Returns: Status of the send procedure. Usually LSD_STAT_BUSY is returned, and the send procedure is then performed in background.

Warning: Do not use more than one syncrhonous call at once. You must wait until a syncrhonous call ends to issue another one.

◆ mw_sleep()

void mw_sleep ( int16_t frames )

Sleep the specified amount of frames.

Parameters

[in] frames Number of frames to sleep.

◆ mw_sntp_cfg_get()

enum mw_err mw_sntp_cfg_get	(	char **	tz_str,
		char *	server[3]
	)

Get SNTP parameters and timezone configuration.

Parameters

[out]	tz_str	Timezone string (e.g. "CET"). See tzset(3) for details.
[out]	server	Array of three NTP server pointers. If less than 3 servers are configured, unused ones will be NULL.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_sntp_cfg_set()

enum mw_err mw_sntp_cfg_set	(	const char *	tz_str,
		const char *	server[3]
	)

Configure SNTP parameters and timezone.

Parameters

[in]	tz_str	Timezone string (e.g. "CET"). See tzset(3) for details.
[in]	server	Array of up to three NTP servers. If less than three servers are desired, unused entries must be empty.

Returns: MW_ERR_NONE on success, other code on failure.

Note: After a successful invocation, call mw_cfg_save() for changes to be persistent

◆ mw_sock_conn_wait()

enum mw_err mw_sock_conn_wait	(	uint8_t	ch,
		int16_t	tout_frames
	)

Polls a socket until it is ready to transfer data. Typical use of this function is after a successful mw_tcp_bind().

Parameters

[in]	ch	Channel associated to the socket to monitor.
[in]	tout_frames	Maximum number of frames to wait for connection. Set to 0 for an infinite wait.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_sock_stat_get()

enum mw_sock_stat mw_sock_stat_get ( uint8_t ch )

Get socket status.

Parameters

[in] ch Channel associated to the socket asked for status.

Returns: Socket status data on success, or -1 on error.

◆ mw_sys_stat_get()

union mw_msg_sys_stat * mw_sys_stat_get ( void )

Get system status.

Returns: Pointer to system status structure on success, or NULL on error.

◆ mw_tcp_bind()

enum mw_err mw_tcp_bind	(	uint8_t	ch,
		uint16_t	port
	)

Binds a socket to a port, and listens to connections on the port. If a connection request is received, it will be automatically accepted.

Parameters

[in]	ch	Channel associated to the socket bound t port.
[in]	port	Port number to which the socket will be bound.

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_tcp_connect()

enum mw_err mw_tcp_connect	(	uint8_t	ch,
		const char *	dst_addr,
		const char *	dst_port,
		const char *	src_port
	)

Tries establishing a TCP connection with specified server.

Parameters

[in]	ch	Channel used for the connection.
[in]	dst_addr	Address (IP or DNS entry) of the server.
[in]	dst_port	Port in which server is listening.
[in]	src_port	Port from which try establishing connection. Set to 0 or empty string for automatic port allocation.

Returns: MW_ERR_NONE on success, other code if connection failed.

◆ mw_udp_reuse_recv()

static enum lsd_status mw_udp_reuse_recv	(	struct mw_reuse_payload *	data,
		int16_t	len,
		void *	ctx,
		lsd_recv_cb	recv_cb
	)

inlinestatic

Receive data using an UDP socket in reuse mode.

Parameters

[in]	data	Receive buffer including the remote address and the data payload.
[in]	len	Length of the receive buffer.
[in]	ctx	Context pointer to pass to the reception callbak.
[in]	recv_cb	Callback to run when reception is complete or errors.

Returns: Status of the receive procedure.

Definition at line 483 of file megawifi.h.

◆ mw_udp_reuse_send()

static enum lsd_status mw_udp_reuse_send	(	uint8_t	ch,
		const struct mw_reuse_payload *	data,
		int16_t	len,
		void *	ctx,
		lsd_send_cb	send_cb
	)

inlinestatic

Send data using a UDP socket in reuse mode.

Parameters

[in]	ch	Channel to use for the send operation.
[in]	data	Send buffer including the remote address and the data payload.
[in]	len	Length of the receive buffer.
[in]	ctx	Context pointer to pass to the reception callbak.
[in]	send_cb	Callback to run when sending completes or errors.

Returns: Status of the receive procedure.

Definition at line 501 of file megawifi.h.

◆ mw_udp_set()

enum mw_err mw_udp_set	(	uint8_t	ch,
		const char *	dst_addr,
		const char *	dst_port,
		const char *	src_port
	)

Configures a UDP socket to send/receive data.

Parameters

[in]	ch	Channel used for the connection.
[in]	dst_addr	Address (IP or DNS entry) to send data to.
[in]	dst_port	Port to send data to.
[in]	src_port	Local port to listen message on.

Returns: MW_ERR_NONE on success, other code if connection failed.

Note: Setting to NULL dst_addr and/or dst_port, enables reuse mode.

◆ mw_version_get()

enum mw_err mw_version_get	(	uint8_t	version[3],
		char **	variant
	)

Obtain module version numbers and string.

Parameters

[out]	version	Version numbers (major, minor, micro) in order.
[out]	variant	String with firmware variant ("std" for standard).

Returns: MW_ERR_NONE on success, other code on failure.

◆ mw_wifi_adv_cfg_get()

struct mw_wifi_adv_cfg * mw_wifi_adv_cfg_get ( void )

Get advanced WiFi configuration.

Returns: Pointer to the advanced WiFi configuration, or NULL on error.

◆ mw_wifi_adv_cfg_set()

enum mw_err mw_wifi_adv_cfg_set ( const struct mw_wifi_adv_cfg * wifi )

Set advanced WiFi configuration.

Returns: MW_ERR_NONE on success, other code on failure.

Warning: This function is dangerous. Changing these parameters is rarely needed, and setting incorrect values, may render the connection unstable and/or crash the WiFi module. Invalid configurations can even cause the module to crash in a bootloop, requiring a programmer to unbrick it. Make sure you thoroughly test the values you allow users to set here.

Note: If you want to change WiFi parameters, the recommendation is to get the current configuration via mw_wifi_adv_cfg_get(), and from it change only the required parameters.; These parameters will not take effect until saved to non-volatile storage (with mw_cfg_save()) and issuing a module reboot.

Modules

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MW_API_VERSION_MAJOR

◆ MW_API_VERSION_MINOR

◆ MW_ASSOC_TOUT_MS

◆ MW_ASSOC_WAIT_SLEEP_MS

◆ MW_CMD_MIN_BUFLEN

◆ MW_COMMAND_TOUT_MS

◆ MW_CONNECT_TOUT_MS

◆ MW_CTRL_CH

◆ MW_FSM_QUEUE_LEN

◆ MW_HTTP_CH

◆ MW_HTTP_OPEN_TOUT_MS

◆ MW_MAX_SOCK

◆ mw_module_reset

◆ mw_module_start

◆ MW_NTP_POOL_MAXLEN

◆ MW_NUM_CFG_SLOTS

◆ MW_NUM_DNS_SERVERS

◆ MW_PASS_MAXLEN

◆ MW_SCAN_TOUT_MS

◆ MW_SSID_MAXLEN

◆ MW_STAT_POLL_MS

◆ mw_tcp_disconnect

◆ mw_udp_unset

◆ MW_UPGRADE_TOUT_MS

Enumeration Type Documentation

◆ mw_err

◆ mw_http_method

◆ mw_if_type

Function Documentation

◆ mw_ap_assoc()

◆ mw_ap_assoc_wait()

◆ mw_ap_cfg_get()

◆ mw_ap_cfg_set()

◆ mw_ap_disassoc()

◆ mw_ap_fill_next()

◆ mw_ap_scan()

◆ mw_bssid_get()

◆ mw_cfg_save()

◆ mw_close()

◆ mw_cmd_data_cb_set()

◆ mw_cmd_recv()

◆ mw_cmd_send()

◆ mw_date_time_get()

◆ mw_def_ap_cfg()

◆ mw_def_ap_cfg_get()

◆ mw_def_server_get()

◆ mw_def_server_set()

◆ mw_default_cfg_set()

◆ mw_detect()

◆ mw_factory_settings()

◆ mw_flash_id_get()

◆ mw_flash_read()

◆ mw_flash_sector_erase()

◆ mw_flash_write()

◆ mw_fw_upgrade()

◆ mw_ga_endpoint_set()

◆ mw_ga_key_value_add()

◆ mw_ga_request()

◆ mw_gamertag_get()

◆ mw_gamertag_set()

◆ mw_hrng_get()

◆ mw_http_cert_query()

◆ mw_http_cert_set()

◆ mw_http_cleanup()

◆ mw_http_finish()

◆ mw_http_header_add()

◆ mw_http_header_del()

◆ mw_http_method_set()

◆ mw_http_open()

◆ mw_http_url_set()

◆ mw_init()

◆ mw_ip_cfg_get()

◆ mw_ip_cfg_set()