ST SPWF04S Series User manual

Introduction
The SPWF04Sx series of Wi-Fi modules integrate a complete TCP/IP protocol stack and a rich set of applications including, but
not limited to, web server, web client RESTful API, TFTP, MQTT and SMTP.
Security is added in the multiple layers of Wi-Fi and peer-to-peer protocols. The stack implements the WPS protocol, WPA2 in
both the Personal and Enterprise options, and the TLS for end-to-end secure transactions.
Users access the features of the SPWF04Sx modules via UART using the simple AT command syntax, or via SPI using a
custom packet format and protocol.
To enable a complete customization of the application on the module, the SPWF04Sx software integrates a MicroPython
interpreter that provides the user with MicroPython standard libraries and a customized set of classes to export the specific
SPWF04Sx features.
The diagram below summarizes the possible integrations of an SPWF04Sx module in a target application.
Figure 1. SPWF04Sx user integration modes
This user manual is intended as a guide to the set of commands available on the UART or the SPI console. A description and
explanation of the configuration variables, status variables and asynchronous indication messages is available in the Appendix
of the manual.
This manual is not intended as a technical guide of Wi-Fi and TCP/IP, or other technologies available in the module.
TCP/IP protocol stack for SPWF04Sx Wi-Fi modules
UM2114
User manual
UM2114 - Rev 3 - November 2018
For further information contact your local STMicroelectronics sales office.
www.st.com

1SPWF04Sx software architecture description
The complete SW architecture of SPWF04S is shown in the diagram below.
Figure 2. SPWF04Sx software architecture
A block diagram of the SPWF04Sx protocol stack is provided in Figure 3. SPWF04Sx protocol stack diagram.
UM2114
SPWF04Sx software architecture description
UM2114 - Rev 3 page 2/66

Figure 3. SPWF04Sx protocol stack diagram
UM2114
SPWF04Sx software architecture description
UM2114 - Rev 3 page 3/66

2Interface and message types
As shown in Figure 1. SPWF04Sx user integration modes, the SPWF04Sx enables three options for integration of
the device in the final user application. Refer to the SPWF04Sx datasheet for information useful for
implementation, such as the pinout. The configuration variable, “console_enabled”, is used to define the module
interface to use.
•UART interface
“console_enabled=1”
The UART console provides a user-friendly interface built on a set of AT commands that allow an external
microcontroller connected to the SPWF04Sx UART to access the functions integrated in SPWF04Sx device.
UART is set as the module's default interface.
•SPI interface
“console_enabled=0”
The device can be connected as a slave to the SPI interface of an external microcontroller. An ad hoc SPI
protocol and corresponding packet format are defined.
•MicroPython scripting
"console_enabled=2” - to use Python together with AT commands over UART.
"console_enabled=3” - to use MicroPython only.
The device implements a scripting methodology based on an integrated MicroPython interpreter.
MicroPython scripts can map a target application, making it unnecessary to integrate the device with an
external processor.
The following four message types represent the type of data exchanged over the interfaces.
•Commands
Used to activate a feature defined within the stack. The list of commands supported is specified in
Table 1. SPWF04Sx commands.
•Command return messages
Synchronous messages that report the status of the execution of a command. The list of synchronous error
codes is reported in Section 8 in the Appendix.
•WINDs
Asynchronous messages reporting a network or radio status at the application level. The list of WIND
messages is reported in Section 8 in the Appendix.
•Data
Data sent to, or received (data payload) from, a remote device.
Table 1. SPWF04Sx commands
Command ID AT command Description
Utils: commands for debugging and retrieving module status
0x01 AT Null command
0x02 AT+S.HELP Help command
0x05 AT+S.STS Status configuration
0x35 AT+S.PEERS Peers configuration
Management: commands for module management and configuration
0x03 AT+S.RESET SW reset
0x04 AT+S.PMS Set power mode
0x08 AT+S.PYTHON Enter MicroPython execution
0x09 AT+S.GCFG Read Configuration status
UM2114
Interface and message types
UM2114 - Rev 3 page 4/66

Command ID AT command Description
0x0A AT+S.SCFG Set configuration variables
0x0B AT+S.WCFG Save configuration to Flash
0x0C AT+S.FCFG Restore factory configuration
0x57 AT+S.FSWRITE FS update via serial UART/SPI
0x58 AT+S.FSUPDATE FS download
0x56 AT+S.FWUPDATE FW download
STM32 peripherals: commands to manage the peripherals and related values
0x13 AT+S.GPIOC Configure GPIO
0x14 AT+S.GPIOR Read GPIO
0x15 AT+S.GPIOW Write GPIO
0x16 AT+S.DAC Disable/Enable DAC
0x17 AT+S.ADC Read ADC value
0x18 AT+S.PWM Set PWM
0x11 AT+S.TIME Get/Set time
0x12 AT+S.RANDOM Provide random number
File system management
0x21 AT+S.FSM Mount volume
0x22 AT+S.FSU Umount/Erase volume
0x23 AT+S.FSC Create file, append data
0x25 AT+S.FSD Delete file
0x26 AT+S.FSR Rename file
0x27 AT+S.FSL List existing files
0x28 AT+S.FSP Print file content
0x29 AT+S.HASH Compute digest
Security: commands to interact with the security features
0x2A AT+S.WPAECERT Manage WPA-Enterprise certificates
0x2B AT+S.TLSCERT Manage TLS certificates
0x36 AT+S.WPS Initiate a WPS Exchange
Radio: commands to manage main Wi-Fi operations
0x32 AT+S.WIFI Set Wi-Fi radio
0x33 AT+S.SCAN Network scan
0x34 AT+S.SSIDTXT Get/Set ASCII SSID
0x39 AT+S.PING Ping a specified host
Sockets: commands to manage socket read and write
0x41 AT+S.SOCKON Open a socket client
0x42 AT+S.SOCKQ Query a socket client for pending data
0x43 AT+S.SOCKC Close a socket client
0x44 AT+S.SOCKW Write data to a socket server
0x45 AT+S.SOCKR Read data from a socket client
0x46 AT+S.SOCKL List opened socket clients
UM2114
Interface and message types
UM2114 - Rev 3 page 5/66

Command ID AT command Description
0x47 AT+S.SOCKDON Open a socket server
0x48 AT+S.SOCKDQ Query socket server for pending data
0x49 AT+S.SOCKDC Close a socket server
0x4A AT+S.SOCKDW Write data to a socket server
0x4B AT+S.SOCKDR Read data from a socket server
0x4C AT+S.SOCKDL List bound socket clients
Web sockets
0x61 AT+S.WSOCKON Open a web socket client
0x62 AT+S.WSOCKQ Query a web socket client for pending data
0x63 AT+S.WSOCKC Close web socket client
0x64 AT+S.WSOCKW Write data to a web socket client
0x65 AT+S.WSOCKR Read data from web socket client
0x66 AT+S.WSOCKL List open web socket client
Trivial FTP
0x51 AT+S.TFTPGET Get request to a TFTP server
0x52 AT+S.TFTPPUT Put request to a TFTP server
SMTP
0x53 AT+S.SMTP Send an email
HTTP
0x54 AT+S.HTTPGET Get a request to an HTTP server
0x55 AT+S.HTTPPOST Post request to an HTTP server
0x59 AT+S.INPUTSSI Fill buffer for raw text input SSI
MQTT
0x5A AT+S.MQTTCONN MQTT connect
0x5B AT+S.MQTTSUB MQTT subscribe
0x5C AT+S.MQTTPUB MQTT publish
0x5D AT+S.MQTTUNSUB MQTT unsubscribe
0x5E AT+S.MQTTDISC MQTT disconnect
UM2114
Interface and message types
UM2114 - Rev 3 page 6/66

3AT commands over the UART
The factory module configuration sets the UART console mode as the default interface for the SPWF04Sx. This
corresponds to the configuration variable “console_enabled” being set to 1.
AT commands over the UART have a max length of 512 bytes; they are case insensitive and are always in the
form of:
AT+S. <cmd-parameters><cr>[data]
Note: Any command requiring data after the <cr> is not reentrant. If bytes are lost during data transfer over the
UART, the module remains in the waiting stage for incoming bytes.
A command is followed by a variable number of response lines that have the following format:
AT-S. <response-string><optional-parameters>
The AT command line, up to the terminating <cr>, is sent from the host. Response lines are sent from the module
to the host.
AT-S.OK:<free_heap>:<wifi_state>
returned when a command is successfully executed.
Note that free_heap and wifi_state are shown depending on
the "console_verbose" configuration variable value (0 to 2).
AT-S.ERROR:<error-code>:<error-string>
qualifies a synchronous error. The <error-code> field of each
asynchronous indication type is unique. The descriptive string
may be safely ignored.
Note that error_code and error_string are shown depending
on the "console_errs" configuration variable value (0 to 2).
Command parameters
A command can require parameters that follow an “=” character. The parameters are positional and separated by
a configurable separator (by default, a comma).
Parameters can require mandatory or optional values. In the latter case, if the value is not specified a default
value will be used. In the format of the command, an optional parameter is represented in squared brackets.
Asynchronous indications
Asynchronous indications may arrive at any time (except as noted below), and have the format:
+WIND:<number>:<descriptive-string>[:<variables>]<cr><lf>
The <number> field of each asynchronous indication type is unique. The descriptive string may be safely ignored.
Note that number and descriptive strings are shown depending on the "console_winds" configuration variable
value (0 to 2).
Refer to Section 8 in the Appendix for a complete list of WIND messages.
Note: Immediately after reset, no commands should be sent and only asynchronous indications are present until
the indication “+WIND:0:Console active<cr><lf>” is received. After this event, AT commands may be safely sent to
the device.
UM2114
AT commands over the UART
UM2114 - Rev 3 page 7/66

4SPI protocol
By setting to 0 the configuration variable "console_enabled", the module is enabled to use the SPI interface in
place of the UART.
The data transferred over the MISO and MOSI signals are packed using a well-defined API packet format as
represented below.
Figure 4. SPI packet formats
Table 2. KindOfEvent Byte SubField
Bits Event type
Bits 0:3 Status variable wifi_state values range. Refer to
Table 8. Status variables.
Bits 4:7
Allowed values are:
• 0x01 for common indications like WIND or action
confirmations
• 0x02 for critical error notifications
• 0x03 for incoming data sent over the SPI (in this case
normally data are filled into payload field)
Table 3. Indication number field
Event type Bits 4:7 Indication number
0x01 Refer to Table 14. WIND messages.
0x02 Refer to Table 10. AT-S.ERROR:=ERROR ID= =ERROR
String=.
0x03 Data payload.
Commands over the SPI have a max length of 512 bytes.
To map an AT command in the equivalent SPI command, the following procedure applies:
1. Use the corresponding CMD ID specified in Table 1. SPWF04Sx commands and fill the 4th bytes of the
master packet.
2. If optional parameters are available, count the number of comma-separated items after the “=” character and
with that number the 6th byte of the message. Starting from the 7th byte, start to write 1 byte containing the
field lengths and then copy the field bytes. Then continue with the remaining parameters.
UM2114
SPI protocol
UM2114 - Rev 3 page 8/66

3. Once the full payload has been filled, calculate the full message payload lengths and accordingly fill bytes 1
and 2 in the SPI message packet request.
First example
AT command: AT+S.FSL
1. Command ID: 0x25
2. Number of parameters: 0x00
3. Full message payload length: 0x02
Result: SPI message 0x02 0x00 0x02 0x25 0x00
Second example
AT command: AT+S.SCAN=d,/scan.txt
1. Command ID: 0x33
2. Number of parameters: 0x02
a. First Parameter: 0x01,d
b. Second Parameter: 0x09,"/scan.txt"
3. Full message payload length: 0x0D
Result: SPI Message 0x02 0x00 0x0D 0x33 0x02 0x01 d 0x09 "/scan.txt"
Third example
AT command: AT+S.SOCKW=0,5<Cr>hello
1. Command ID: 0x44
2. Number of parameters: 0x02
a. First Parameter: 0x01,0
b. Second Parameter: 0x01,5
3. Payload: "hello"
Result: SPI Message 0x02 0x00 0x0B 0x44 0x02 0x01 0 0x01 5 "hello"
Fourth example
Asynchronous event: +WIND:1:Poweron:170726-b7ac1ba-SPWF04S
1. kind of event (4bits): 0x01
2. wifi_state (4 bits): 0x0
3. Indication number: 0x01
4. Full message payload length: 0x16
Result: SPI Message 0x02 0x10 0x01 0x16 0x00 (170726-b7ac1ba-SPWF04S)
UM2114
SPI protocol
UM2114 - Rev 3 page 9/66

5MicroPython scripting
The SPWF04Sx supports the MicroPython modes represented in Figure 5. MicroPython modes. The configuration
variable “console_enabled” identifies the use of the console together with MicroPython. In detail:
• "console_enabled" set to 2: this setting allows using both AT commands over the UART and MicroPython
REPL shell.
• "console_enabled" set to 3: this setting allows only a MicroPython preloaded script to be executed. No
UART/SPI communication is allowed to/from a host processor.
Consequently, the following Python modes are defined:
•Python Interactive Console (REPL – Read Evaluation Print Loop). Mainly used for debugging purposes,
it is activated by the AT+S.Python (Python command) launched without parameters. The REPL is exited by
using a CTRL-D escape character.
•Run Time Script execution. Activated with the Python command, it allows to execute the script specified as
parameter. After script execution, control returns to the AT console.
•DefaultScript Hard Execution. By using the GPIO(8) set to high at boot time, or when "console_enabled" is
set to 3, the module automatically enters the execution of the script specified by the variable “python_script”.
This mode allows the use of the module without a connected host. Note that "console_enabled" is not
changed by GPIO(8) access: this means that on the subsequent reboot, accessing Python mode again will
require GPIO(8) to be high.
Figure 5. MicroPython modes
UM2114
MicroPython scripting
UM2114 - Rev 3 page 10/66