romdev-mcp 0.1.1

package/src/platforms/genesis/lib/sgdk/include/ext/mw/megawifi.h

@@ -0,0 +1,984 @@
+/************************************************************************//**
+ * \file
+ *
+ * \brief MegaWiFi API implementation.
+ *
+ * \defgroup megawifi megawifi
+ * \{
+ *
+ * \brief 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)
+ * \author Juan Antonio (PaCHoN)
+ * \date 2025
+ * 
+ * \note This module requires setting MODULE_MEGAWIFI to 1 in config.h and
+ * rebuilding the library (if you had to change them).
+ ****************************************************************************/
+
+#ifndef _MEGAWIFI_H_
+#define _MEGAWIFI_H_
+
+#include "ext/mw/mw-msg.h"
+#include "ext/mw/lsd.h"
+#include "ext/mw/comm.h"
+
+/// API version implemented, major number
+#define MW_API_VERSION_MAJOR	1
+
+/// API version implemented, minor number
+#define MW_API_VERSION_MINOR	5
+
+/// Timeout for standard commands in milliseconds
+#define MW_COMMAND_TOUT_MS	2000
+/// Timeout for TCP connections
+#define MW_CONNECT_TOUT_MS	10000
+/// Timeout for HTTP open command in milliseconds
+#define MW_HTTP_OPEN_TOUT_MS	10000
+/// Timeout for the AP scan command in milliseconds
+#define MW_SCAN_TOUT_MS		10000
+/// Timeout for the AP associate command in milliseconds
+#define MW_ASSOC_TOUT_MS	20000
+/// Time to sleep before waiting for assoc in milliseconds
+#define MW_ASSOC_WAIT_SLEEP_MS	5000
+/// Timeout for upgrade command in milliseconds
+#define MW_UPGRADE_TOUT_MS	600000
+/// Timeout for ping command in milliseconds
+#define MW_PING_TOUT_MS	30000
+/// Milliseconds between status polls while in wm_ap_assoc_wait()
+#define MW_STAT_POLL_MS		250
+
+/// Error codes for MegaWiFi API functions
+enum mw_err {
+	MW_ERR_NONE = 0,		///< 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
+};
+
+/// Supported HTTP methods
+enum mw_http_method {
+    MW_HTTP_METHOD_GET = 0,    ///< 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
+    MW_HTTP_METHOD_MAX,
+};
+
+/// Maximum SSID length (including '\0').
+#define MW_SSID_MAXLEN		32
+/// Maximum password length (including '\0').
+#define MW_PASS_MAXLEN		64
+/// Maximum length of an NTP pool URI (including '\0').
+#define MW_NTP_POOL_MAXLEN	80
+/// Number of AP configurations stored to nvflash.
+#define MW_NUM_CFG_SLOTS	3
+/// Number of DSN servers supported per AP configuration.
+#define MW_NUM_DNS_SERVERS	2
+/// Length of the FSM queue
+#define MW_FSM_QUEUE_LEN	8
+/// Maximum number of simultaneous TCP connections
+#define MW_MAX_SOCK			3
+/// Control channel used for LSD protocol
+#define MW_CTRL_CH			0
+/// Channel used for HTTP requests and cert sets
+#define MW_HTTP_CH			LSD_MAX_CH - 1
+
+/// 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).
+#define MW_CMD_MIN_BUFLEN	168
+
+/// Access Point data.
+struct mw_ap_data {
+	enum mw_security auth;	///< Security type
+	uint8_t channel;	///< WiFi channel.
+	int8_t rssi;		///< Signal strength.
+	uint8_t ssid_len;	///< Length of ssid field.
+	char *ssid;		///< SSID string (not NULL terminated).
+};
+
+/// Interface type for the mw_bssid_get() function.
+enum mw_if_type {
+	MW_IF_STATION = 0,	///< Station interface
+	MW_IF_SOFTAP,		///< Access Point interface
+	MW_IF_MAX		///< Number of supported interface types
+};
+
+/************************************************************************//**
+ * \brief Module initialization. Must be called once before using any
+ *        other function. It also initializes de UART.
+ *
+ * \param[in] cmd_buf Pointer to the buffer used to send and receive commands.
+ * \param[in] buf_len Length of cmdBuf in bytes.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+int16_t mw_init(uint16_t *cmd_buf, uint16_t buf_len);
+
+/************************************************************************//**
+ * \brief 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.
+ ****************************************************************************/
+static inline void mw_process(void)	{lsd_process();}
+
+/************************************************************************//**
+ * \brief Sets the callback function to be run when network data is received
+ * while waiting for a command reply.
+ *
+ * \param[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.
+ ****************************************************************************/
+void mw_cmd_data_cb_set(lsd_recv_cb cmd_recv_cb);
+
+/************************************************************************//**
+ * \brief Performs the startup sequence for the WiFi module, and tries
+ * detecting it by requesting the version data.
+ *
+ * \param[out] major   Major version number.
+ * \param[out] minor   Minor version number.
+ * \param[out] variant String with firmware variant ("std" for standard).
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_detect(uint8_t *major, uint8_t *minor, char **variant);
+
+/************************************************************************//**
+ * \brief Obtain module version numbers and string
+ *
+ * \param[out] version Version numbers (major, minor, micro) in order.
+ * \param[out] variant String with firmware variant ("std" for standard).
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_version_get(uint8_t version[3], char **variant);
+
+/************************************************************************//**
+ * \brief Gets the module BSSID (the MAC address) for the specified interface.
+ *
+ * \param[in] interface_type Type of the interface to obtain BSSID from.
+ *
+ * \return The requested BSSID (6 byte binary data), or NULL on error.
+ ****************************************************************************/
+uint8_t *mw_bssid_get(enum mw_if_type interface_type);
+
+/************************************************************************//**
+ * \brief Set default module configuration (AKA factory settings).
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ *
+ * \note For this command to take effect, it must be followed by a module
+ *       reset.
+ ****************************************************************************/
+enum mw_err mw_default_cfg_set(void);
+
+/************************************************************************//**
+ * \brief Set access point configuration (SSID and password).
+ *
+ * \param[in] slot Configuration slot to use.
+ * \param[in] ssid String with the AP SSID to set.
+ * \param[in] pass String with the AP SSID to set.
+ * \param[in] phy_type Bitmask with the PHY type configuration.
+ *
+ * \return 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.
+ * \note After a successful invocation, call mw_cfg_save() for changes to
+ * be persistent
+ ****************************************************************************/
+enum mw_err mw_ap_cfg_set(uint8_t slot, const char *ssid, const char *pass,
+		 enum mw_phy_type phy_type);
+
+/************************************************************************//**
+ * \brief Gets access point configuration (SSID and password).
+ *
+ * \param[in]  slot Configuration slot to use.
+ * \param[out] ssid String with the AP SSID got.
+ * \param[out] pass String with the AP SSID got.
+ * \param[out] phy_type Bitmask with the PHY type configuration.
+ *
+ * \return 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.
+ ****************************************************************************/
+enum mw_err mw_ap_cfg_get(uint8_t slot, char **ssid, char **pass,
+		enum mw_phy_type *phy_type);
+
+/************************************************************************//**
+ * \brief Set IPv4 configuration.
+ *
+ * \param[in] slot Configuration slot to use.
+ * \param[in] ip   Pointer to the mw_ip_cfg structure, with IP configuration.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ *
+ * \note After a successful invocation, call mw_cfg_save() for changes to
+ * be persistent
+ ****************************************************************************/
+enum mw_err mw_ip_cfg_set(uint8_t slot, const struct mw_ip_cfg *ip);
+
+/************************************************************************//**
+ * \brief Get IPv4 configuration.
+ *
+ * \param[in]  slot Configuration slot to use.
+ * \param[out] ip   Double pointer to mw_ip_cfg structure, with IP conf.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_ip_cfg_get(uint8_t slot, struct mw_ip_cfg **ip);
+
+/************************************************************************//**
+ * \brief Set advanced WiFi configuration.
+ *
+ * \return 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.
+ * \note These parameters will not take effect until saved to non-volatile
+ * storage (with mw_cfg_save()) and issuing a module reboot.
+ ****************************************************************************/
+enum mw_err mw_wifi_adv_cfg_set(const struct mw_wifi_adv_cfg *wifi);
+
+/************************************************************************//**
+ * \brief Get advanced WiFi configuration.
+ *
+ * \return Pointer to the advanced WiFi configuration, or NULL on error.
+ ****************************************************************************/
+struct mw_wifi_adv_cfg *mw_wifi_adv_cfg_get(void);
+
+/************************************************************************//**
+ * \brief Saves changed configuration parameters to non-volatile memory.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_cfg_save(void);
+
+/************************************************************************//**
+ * \brief Get current IP configuration, of the joined AP.
+ *
+ * \param[out] ip Double pointer to mw_ip_cfg structure, with IP conf.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_ip_current(struct mw_ip_cfg **ip);
+
+/************************************************************************//**
+ * \brief Scan for access points.
+ *
+ * \param[in]  phy_type Bitmask with the PHY type configuration.
+ * \param[out] ap_data Data of the found access points. Each entry has the
+ *             format specified on the mw_ap_data structure.
+ * \param[out] aps     Number of found access points.
+ *
+ * \return Length in bytes of the output data if operation completes
+ *         successfully, or -1 if scan fails.
+ ****************************************************************************/
+int16_t mw_ap_scan(enum mw_phy_type phy_type, char **ap_data, uint8_t *aps);
+
+/************************************************************************//**
+ * \brief 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.
+ *
+ * \param[in]  ap_data  Access point data obtained from mw_ap_scan().
+ * \param[in]  pos      Position at which to extract data.
+ * \param[out] apd      Pointer to the extracted data from an AP.
+ * \param[in]  data_len Lenght of apData.
+ *
+ * \return 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.
+ ****************************************************************************/
+int16_t mw_ap_fill_next(const char *ap_data, uint16_t pos,
+		struct mw_ap_data *apd, uint16_t data_len);
+
+/************************************************************************//**
+ * \brief Tries associating to an AP. If successful, also configures IPv4.
+ *
+ * \param[in] slot Configuration slot to use.
+ *
+ * \return MW_ERR_NONE if AP join operation has been successfully started,
+ ****************************************************************************/
+enum mw_err mw_ap_assoc(uint8_t slot);
+
+/************************************************************************//**
+ * \brief Polls the module status until it reports device is associated to
+ * AP or timeout occurs.
+ *
+ * \param[in] tout_frames Maximun number of frames to wait for association.
+ *            Set to TSK_PEND_FOREVER for an infinite wait.
+ *
+ * \return MW_ERR_NONE if device is associated to AP. MW_ERR_NOT_READY if
+ * the timeout has expired.
+ ****************************************************************************/
+enum mw_err mw_ap_assoc_wait(int16_t tout_frames);
+
+/************************************************************************//**
+ * \brief Sets default AP/IP configuration.
+ *
+ * \param[in] slot Configuration slot to use.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ *
+ * \note After a successful invocation, call mw_cfg_save() for changes to
+ * be persistent
+ ****************************************************************************/
+enum mw_err mw_def_ap_cfg(uint8_t slot);
+
+/************************************************************************//**
+ * \brief Dissasociates from a previously associated AP.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_ap_disassoc(void);
+
+/************************************************************************//**
+ * \brief Gets default AP/IP configuration slot.
+ *
+ * \return The default configuration slot, of -1 on error.
+ ****************************************************************************/
+int16_t mw_def_ap_cfg_get(void);
+
+/************************************************************************//**
+ * \brief Tries establishing a TCP connection with specified server.
+ *
+ * \param[in] ch       Channel used for the connection.
+ * \param[in] dst_addr Address (IP or DNS entry) of the server.
+ * \param[in] dst_port Port in which server is listening.
+ * \param[in] src_port Port from which try establishing connection. Set to
+ *                     0 or empty string for automatic port allocation.
+ *
+ * \return MW_ERR_NONE on success, other code if connection failed.
+ ****************************************************************************/
+enum mw_err mw_tcp_connect(uint8_t ch, const char *dst_addr,
+		const char *dst_port, const char *src_port);
+
+/************************************************************************//**
+ * \brief Closes and disconnects a socket from specified channel.
+ *
+ * This function can be used to free the channel associated to both TCP and
+ * UDP sockets.
+ *
+ * \param[in] ch Channel associated to the socket to disconnect.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_close(uint8_t ch);
+
+/// Closes a TCP socket. This is an alias of mw_close().
+#define mw_tcp_disconnect(ch)	mw_close(ch)
+
+/************************************************************************//**
+ * \brief Configures a UDP socket to send/receive data.
+ *
+ * \param[in] ch       Channel used for the connection.
+ * \param[in] dst_addr Address (IP or DNS entry) to send data to.
+ * \param[in] dst_port Port to send data to.
+ * \param[in] src_port Local port to listen message on.
+ *
+ * \return MW_ERR_NONE on success, other code if connection failed.
+ *
+ * \note Setting to NULL dst_addr and/or dst_port, enables reuse mode.
+ ****************************************************************************/
+enum mw_err mw_udp_set(uint8_t ch, const char *dst_addr, const char *dst_port,
+		const char *src_port);
+
+/// Frees a UDP socket. This is an alias of mw_close().
+#define mw_udp_unset(ch)	mw_close(ch)
+
+/************************************************************************//**
+ * \brief Binds a socket to a port, and listens to connections on the port.
+ *        If a connection request is received, it will be automatically
+ *        accepted.
+ *
+ * \param[in] ch   Channel associated to the socket bound t port.
+ * \param[in] port Port number to which the socket will be bound.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_tcp_bind(uint8_t ch, uint16_t port);
+
+/************************************************************************//**
+ * \brief Polls a socket until it is ready to transfer data. Typical use of
+ * this function is after a successful mw_tcp_bind().
+ *
+ * \param[in] ch          Channel associated to the socket to monitor.
+ * \param[in] tout_frames Maximum number of frames to wait for connection.
+ *            Set to 0 for an infinite wait.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_sock_conn_wait(uint8_t ch, int16_t tout_frames);
+
+/************************************************************************//**
+ * \brief Receive data, asyncrhonous interface.
+ *
+ * \param[in] buf     Reception buffer.
+ * \param[in] len     Length of the receive buffer.
+ * \param[in] ctx     Context pointer to pass to the reception callbak.
+ * \param[in] recv_cb Callback to run when reception is complete or errors.
+ *
+ * \return Status of the receive procedure.
+ ****************************************************************************/
+static inline enum lsd_status mw_recv(char *buf, int16_t len, void *ctx,
+		lsd_recv_cb recv_cb)
+{
+	return lsd_recv(buf, len, ctx, recv_cb);
+}
+
+/************************************************************************//**
+ * \brief Receive data using an UDP socket in reuse mode.
+ *
+ * \param[in] data    Receive buffer including the remote address and the
+ *                    data payload.
+ * \param[in] len     Length of the receive buffer.
+ * \param[in] ctx     Context pointer to pass to the reception callbak.
+ * \param[in] recv_cb Callback to run when reception is complete or errors.
+ *
+ * \return Status of the receive procedure.
+ ****************************************************************************/
+static inline enum lsd_status mw_udp_reuse_recv(struct mw_reuse_payload *data,
+		int16_t len, void *ctx, lsd_recv_cb recv_cb)
+{
+	return lsd_recv((char*)data, len, ctx, recv_cb);
+}
+
+/************************************************************************//**
+ * \brief Send data using a UDP socket in reuse mode.
+ *
+ * \param[in] ch      Channel to use for the send operation.
+ * \param[in] data    Send buffer including the remote address and the
+ *                    data payload.
+ * \param[in] len     Length of the receive buffer.
+ * \param[in] ctx     Context pointer to pass to the reception callbak.
+ * \param[in] send_cb Callback to run when sending completes or errors.
+ *
+ * \return Status of the receive procedure.
+ ****************************************************************************/
+static inline 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)
+{
+	return lsd_send(ch, (const char*)data, len, ctx, send_cb);
+}
+
+/************************************************************************//**
+ * \brief Sends data through a socket, using a previously allocated channel.
+ * Asynchronous interface.
+ *
+ * \param[in] ch      Channel used to send the data.
+ * \param[in] data    Buffer to send.
+ * \param[in] len     Length of the data to send.
+ * \param[in] ctx     Context for the send callback function.
+ * \param[in] send_cb Callback to run when send completes or errors.
+ *
+ * \return 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.
+ ****************************************************************************/
+static inline enum lsd_status mw_send(uint8_t ch, const char *data, int16_t len,
+		void *ctx, lsd_send_cb send_cb)
+{
+	return lsd_send(ch, data, len, ctx, send_cb);
+}
+
+/************************************************************************//**
+ * \brief Receive data, syncrhonous interface.
+ *
+ * \param[out] ch         Channel on which data was received.
+ * \param[out] buf        Reception buffer.
+ * \param[inout] buf_len  On input, length of the buffer.
+ *                        On output, received data length in bytes.
+ * \param[in] tout_frames Reception timeout in frames. Set to TSK_PEND_FOREVER
+ *                        for infinite wait (dangerous!).
+ *
+ * \return 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.
+ ****************************************************************************/
+enum mw_err mw_recv_sync(uint8_t *ch, char *buf, int16_t *buf_len,
+		int16_t tout_frames);
+
+/************************************************************************//**
+ * \brief Sends data through a socket, using a previously allocated channel.
+ * Synchronous interface.
+ *
+ * \param[in] ch          Channel used to send the data.
+ * \param[in] data        Buffer to send.
+ * \param[in] len         Length of the data to send.
+ * \param[in] tout_frames Timeout for send operation in frames. Set to 0 for
+ *                        infinite wait (dangerous!).
+ *
+ * \return 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.
+ ****************************************************************************/
+enum mw_err mw_send_sync(uint8_t ch, const char *data, uint16_t len,
+		int16_t tout_frames);
+
+/************************************************************************//**
+ * \brief Get system status.
+ *
+ * \return Pointer to system status structure on success, or NULL on error.
+ ****************************************************************************/
+union mw_msg_sys_stat *mw_sys_stat_get(void);
+
+/************************************************************************//**
+ * \brief Get socket status.
+ *
+ * \param[in] ch Channel associated to the socket asked for status.
+ *
+ * \return Socket status data on success, or -1 on error.
+ ****************************************************************************/
+enum mw_sock_stat mw_sock_stat_get(uint8_t ch);
+
+/************************************************************************//**
+ * \brief Configure SNTP parameters and timezone.
+ *
+ * \param[in] tz_str Timezone string (e.g. "CET"). See tzset(3) for details.
+ * \param[in] server Array of up to three NTP servers. If less than three
+ *                   servers are desired, unused entries must be empty.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ *
+ * \note After a successful invocation, call mw_cfg_save() for changes to
+ * be persistent
+ ****************************************************************************/
+enum mw_err mw_sntp_cfg_set(const char *tz_str, const char *server[3]);
+
+/************************************************************************//**
+ * \brief Get SNTP parameters and timezone configuration.
+ *
+ * \param[out] tz_str Timezone string (e.g. "CET"). See tzset(3) for details.
+ * \param[out] server Array of three NTP server pointers. If less than 3
+ *                    servers are configured, unused ones will be NULL.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_sntp_cfg_get(char **tz_str, char *server[3]);
+
+/************************************************************************//**
+ * \brief Get date and time.
+ *
+ * \param[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).
+ *
+ * \return A string with the date and time in textual format, e.g.: "Thu Mar
+ *         3 12:26:51 2016", or NULL if error.
+ ****************************************************************************/
+char *mw_date_time_get(uint32_t dt_bin[2]);
+
+/************************************************************************//**
+ * \brief Get the identifiers of the flash chip in the WiFi module.
+ *
+ * \param[out] man_id ID of the flash chip manufacturer.
+ * \param[out] dev_id Device IDs of the flash chip.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_flash_id_get(uint8_t *man_id, uint16_t *dev_id);
+
+/************************************************************************//**
+ * \brief Erase a 4 KiB Flash sector. Every byte of an erased sector will be
+ *        read as 0xFF.
+ *
+ * \param[in] sect Sector number to erase.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_flash_sector_erase(uint16_t sect);
+
+/************************************************************************//**
+ * \brief Write data to specified flash address.
+ *
+ * \param[in] addr     Address to which data will be written.
+ * \param[in] data     Data to be written to flash chip.
+ * \param[in] data_len Length in bytes of data field.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_flash_write(uint32_t addr, uint8_t *data, uint16_t data_len);
+
+/************************************************************************//**
+ * \brief Read data from specified flash address.
+ *
+ * \param[in] addr     Address from which data will be read.
+ * \param[in] data_len Number of bytes to read from addr.
+ *
+ * \return Pointer to read data on success, or NULL if command failed.
+ ****************************************************************************/
+uint8_t *mw_flash_read(uint32_t addr, uint16_t data_len);
+
+/************************************************************************//**
+ * \brief Set gamertag information for one slot.
+ *
+ * \param[in] slot     Slot to use (from 0 to 2).
+ * \param[in] gamertag Gamertag information to set on specified slot.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ *
+ * \note After a successful invocation, call mw_cfg_save() for changes to
+ * be persistent
+ ****************************************************************************/
+enum mw_err mw_gamertag_set(uint8_t slot, const struct mw_gamertag *gamertag);
+
+/************************************************************************//**
+ * \brief Get gamertag information for one slot.
+ *
+ * \param[in] slot Slot to get gamertag from.
+ *
+ * \return Gamertag information on success, NULL on error.
+ ****************************************************************************/
+struct mw_gamertag *mw_gamertag_get(uint8_t slot);
+
+/************************************************************************//**
+ * \brief Write a message to the WiFi module log trace.
+ *
+ * \param[in] msg Message to write to the log trace.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_log(const char *msg);
+
+/************************************************************************//**
+ * \brief Set factory default configuration.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ * \note It is recommended to reboot the module after this command.
+ ****************************************************************************/
+enum mw_err mw_factory_settings(void);
+
+/************************************************************************//**
+ * \brief Powers off the WiFi module.
+ *
+ * The module will be put in deep sleep mode. To wake it up, the RESET pin
+ * must be toggled.
+ ****************************************************************************/
+void mw_power_off(void);
+
+/************************************************************************//**
+ * \brief Sleep the specified amount of frames
+ *
+ * \param[in] frames Number of frames to sleep.
+ ****************************************************************************/
+void mw_sleep(int16_t frames);
+
+/************************************************************************//**
+ * \brief Set URL for HTTP requests.
+ *
+ * \param[in] url URL to set.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_http_url_set(const char *url);
+
+/************************************************************************//**
+ * \brief Set method for HTTP requests.
+ *
+ * \param[in] method Method to set.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_http_method_set(enum mw_http_method method);
+
+/************************************************************************//**
+ * \brief Add an HTTP header.
+ *
+ * \param[in] key   Header key.
+ * \param[in] value Value to set for the key.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_http_header_add(const char *key, const char *value);
+
+/************************************************************************//**
+ * \brief Delete a previously added HTTP header.
+ *
+ * \param[in] key Key of the header to delete.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_http_header_del(const char *key);
+
+/************************************************************************//**
+ * \brief 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.
+ *
+ * \param[in] content_len Length of the content to write in HTTP request,
+ *            after a successfull call to this function.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_http_open(uint32_t content_len);
+
+/************************************************************************//**
+ * \brief 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.
+ *
+ * \param[out] content_len Length of the response content to receive after a
+ *             successfull call to this function.
+ * \param[in]  tout_frames Maximun number of frames to wait for reply.
+ *
+ * \return 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.
+ ****************************************************************************/
+int16_t mw_http_finish(uint32_t *content_len, int16_t tout_frames);
+
+/************************************************************************//**
+ * \brief Query the X.509 hash of the installed PEM certificate.
+ *
+ * \return 0xFFFFFFFF if certificate is not installed or error occurs, or
+ * the installed X.509 certificate hash on success.
+ ****************************************************************************/
+uint32_t mw_http_cert_query(void);
+
+/************************************************************************//**
+ * \brief 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.
+ *
+ * \param[in] cert_hash X.509 hash of the certificate to set, ignored if
+ *                      cert_len set to 0.
+ * \param[in] cert      PEM certificate in plain text. Ignored if cert_len
+ *                      set to 0.
+ *                      previously stored certificate.
+ * \param[in] cert_len  Certificate length in bytes. Set to 0 to delete a
+ *                      previously stored certificate.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+enum mw_err mw_http_cert_set(uint32_t cert_hash, const char *cert,
+		uint16_t cert_len);
+
+/************************************************************************//**
+ * \brief Clean-up an HTTP request, freeing associated resources.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ ****************************************************************************/
+int16_t mw_http_cleanup(void);
+
+/************************************************************************//**
+ * \brief Get the default server used for MegaWiFi connections.
+ *
+ * \return The server URL string, or NULL on error.
+ ****************************************************************************/
+char *mw_def_server_get(void);
+
+/************************************************************************//**
+ * \brief Set the default server used for MegaWiFi connections.
+ *
+ * \param[in] server_url The server URL to set.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ *
+ * \note After a successful invocation, call mw_cfg_save() for changes to
+ * be persistent
+ ****************************************************************************/
+enum mw_err mw_def_server_set(const char *server_url);
+
+/************************************************************************//**
+ * \brief Get random numbers.
+ *
+ * \param[in] rnd_len Number of bytes of resulting random array.
+ *
+ * \return The buffer with the requested random numbers on success, or NULL
+ * when error.
+ ****************************************************************************/
+uint8_t *mw_hrng_get(uint16_t rnd_len);
+
+/************************************************************************//**
+ * \brief Set endpoint for Game API.
+ *
+ * Example endpoint for GameJolt: "https://api.gamejolt.com/api/game/v1_2/".
+ *
+ * \param[in] endpoint Endpoint for the Game API to set.
+ * \param[in] priv_key Private key used for request signatures.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ *
+ * \note The endpoint set persists between successive mw_ga_request() calls.
+ ****************************************************************************/
+enum mw_err mw_ga_endpoint_set(const char *endpoint, const char *priv_key);
+
+/************************************************************************//**
+ * \brief Add parameters to the Game API request in key/value format.
+ *
+ * Example key:value pair for GameJolt: "game_id":"123456".
+ *
+ * \param[in] key       Array with the keys to add.
+ * \param[in] value     Array with the values to add
+ * \param[in] num_pairs Number of key/value pairs to add.
+ *
+ * \return MW_ERR_NONE on success, other code on failure.
+ *
+ * \note The key/value pairs set persist between successive mw_ga_request()
+ * calls.
+ * \note Call mw_ga_key_value_add(NULL, NULL, 0) to clear previously set
+ * key/value pairs.
+ * \note Key/value pairs must NOT be URL encoded. Encoding is handled
+ * internally.
+ ****************************************************************************/
+enum mw_err mw_ga_key_value_add(const char **key, const char **value,
+		uint16_t num_pairs);
+
+/************************************************************************//**
+ * \brief 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"
+ *
+ * \param[in]  method       HTTP method to use. Most likely MW_HTTP_METHOD_GET.
+ * \param[in]  path         Additional paths to add to the request.
+ * \param[in]  num_paths    Number of additional paths to add.
+ * \param[in]  key          Additional paths to add to the request.
+ * \param[in]  value        Additional paths to add to the request.
+ * \param[in]  num_kv_pairs Number of key/value pairs.
+ * \param[out] content_len   Content length of the API response.
+ * \param[in]  tout_frames   Number of frames to wait before canceling the
+ *             request due to a timeout error.
+ *
+ * \return 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.
+ * \note path, key and value parameters must not be URL encoded. Encoding is
+ * handled internally.
+ ****************************************************************************/
+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);
+
+/************************************************************************//**
+ * \brief List available upgrades WiFi module firmware.
+ *
+ * \param[in] page           Page of list
+ * \param[in] page_size      Page size of list
+ * \param[in] offset         Offset number
+ * \param[out] listUpgrades  Pointer to list of char*
+ * \param[out] len 			 Result length
+ * \param[out] total         Total elements
+ *
+ * \return Status of the send procedure.
+ ****************************************************************************/
+enum mw_err mw_fw_list_upgrades(uint8_t page, uint8_t size, uint8_t offset, char **listUpgrades, uint8_t *len, uint8_t *total);
+
+/************************************************************************//**
+ * \brief Over-The-Air upgrade WiFi module firmware.
+ *
+ * \param[in] name Name of the firmware blob to upgrade.
+ *                 E.g. "mw_rtos_std_v1.4.1"
+ *
+ * \return Status of the send procedure.
+ ****************************************************************************/
+enum mw_err mw_fw_upgrade(const char *name);
+
+/************************************************************************//**
+ * \brief Run ICMP requesto to domain.
+ *
+ * \param[in] domain Domain to ICMP request.
+ *                 E.g. "www.example.com"
+ * \param[in] retries retries to ICMP request
+ *                 E.g. 5
+ *
+ * \return Status of the send procedure.
+ ****************************************************************************/
+struct mw_ping_response *mw_ping(const char* domain, u8 retries);
+
+/****** THE FOLLOWING COMMANDS ARE LOWER LEVEL AND USUALLY NOT NEEDED ******/
+
+/************************************************************************//**
+ * \brief Send a command to the WiFi module.
+ *
+ * \param[in] cmd     Pointer to the filled mw_cmd command structure.
+ * \param[in] ctx     Context for callback function.
+ * \param[in] send_cb Callback for the send operation completion.
+ *
+ * \return Status of the send procedure.
+ ****************************************************************************/
+static inline enum lsd_status mw_cmd_send(mw_cmd *cmd, void *ctx,
+		lsd_send_cb send_cb)
+{
+	// Send data on control channel (0).
+	return lsd_send(MW_CTRL_CH, cmd->packet, cmd->data_len + 4,
+			ctx, send_cb);
+}
+
+/************************************************************************//**
+ * \brief Try obtaining a reply to a command.
+ *
+ * \param[in] rep     Buffer to hold the command reply.
+ * \param[in] ctx     Context for the reception callback.
+ * \param[in] recv_cb Callback for data reception completion.
+ *
+ * \return Status of the reception procedure.
+ ****************************************************************************/
+static inline enum lsd_status mw_cmd_recv(mw_cmd *rep, void *ctx,
+		lsd_recv_cb recv_cb) {
+	return lsd_recv(rep->packet, sizeof(mw_cmd), ctx, recv_cb);
+}
+
+#endif /*_MEGAWIFI_H_*/
+
+/** \} */
+