When working on a Linux system, it can be convenient to use the kernel events tracing mechanism, (described in details in Documentation/trace/events.txt in the Linux kernel sources).
We will only focus on a very simple use case here.
Listing possible event traces
All traceable events are listed under the /sys/kernel/debug/tracing/events/ hierarchy of directories
Access to kernel event tracing is reserved to privileged users, so all instructions below need to be executed with root privileges
Under Linux, SDIO parts are bound to the Linux mmc bus.
Before using a Wi-Fi part connected to the SDIO bus of a Linux system, it is necessary that the system detects the HW on the bus. Linux systems will try to detect SDIO parts on the bus at boot, and every time the mmc bus is bound. The latter is what we will use to trace mmc messages related to SDIO detection.
SDIO Detection message
The following message should be visible in dmesg once boot is complete:
mmcX new high speed SDIO card at address 0001
one-line check:
$ dmesg | grep 'new high speed SDIO'
Until this message is present in dmesg, it is useless to try to load the driver
If this message is not found, it is necessary to debug SDIO detection, going through the following steps:
Retrieving the current device tree
Checking which mmc bus is used for SDIO
Making sure SDIO detection is enabled in the device tree
Checking the mmc bus commands during the SDIO detection phase
Checking the SDIO detection result
These steps are detailed below.
Keep in mind that any change to the device tree is only taken into account on the next reboot, so changing the device tree means rebooting!
NB: The 'dts' format allows the resulting file to be edited in a human-readable format. If edited as if it were a C file you can benefit from code folding to get a better view of the contents.
Making sure SDIO is enabled in Device Tree
In order for the Linux system to try detecting a part on the SDIO bus, it needs to be part of the Device Tree used at boot.
If this returns an empty line, SDIO detection is not even triggered. Refer to your system documentation to know how to add SDIO to the device tree.
Check the SDIO pins allocation in the 'sdio_pins' node to make sure they match your HW
Checking which mmc bus is used for SDIO
one-line check (SDIO mmc bus selection):
$ grep mmc[0-2] device_tree.out
Typical result:
mmc1 = "/soc/sdio@7e300000";
If this returns an empty line, SDIO is not connected to any mmc bus. Refer to your system documentation to know how to add SDIO to the device tree.
Checking the mmc bus commands during the SDIO detection phase
Until all the above checks are ok, it is pointless trying to trace SDIO detection messages, since detection is not even triggered.
This is the trickiest part, since it involves tracking message normally issued at boot, when the system is attempting SDIO detection.
In reality, these are issued every time the mmc bus is bound to the system, so unbinding/binding the mmc bus will trigger a new detection attempt. We use this to avoid activating the traces at boot time, since this is not easy to do.
Preparing the kernel event traces (to be executed with root privileges): Activating mmc request traces:
NB: The attached SDIO_Detection_mmc_request_done_traces.txt file contains the typical traces.
Stopping mmc request traces (once the traces have been retrieved):
This step is necessary to stop tracing, which is otherwise still active. No additional traces are shown because SDIO traffic only uses CMD53 once detection is complete, and CMD53 are filtered out. It is better to stop tracing completely.
If detection is correct, the 'mmcX new high speed SDIO card at address 0001' message is present in dmesg.
Otherwise, check for errors related to the mmc item corresponding to your part.
SDIO pins used for the detection phase
The SDIO detection as shown above only uses SD_CMD and SD_CLK pins, and is generally performed with a 400kHz SD_CLK. SD_DAT[3:0] are not used yet, so SDIO detection may succeed even though SD_DAT[3:0] are not properly routed.
Max SDIO speed too high
During the last steps of SDIO detection, the SoC sets the SDIO part to 'high-speed' mode on 4 data bits, then configures its own hardware to the maximum selected SDIO speed (controllable in the device tree) only at the very end of the SDIO detection, after a long series of about 26 CMD52 commands.
In case there are issues related to the max clock speed, the last CMD52 commands will return with 'cmd_err=-110' (which means 'TIMEOUT'), and will be followed by a short burst of about 4 CMD55 commands.
Whenever the SDIO detection loop fails, it is repeated with a slower clock speed (400, 300, 200, 100 kHz, respectively), but is still ending with the max clock. If the max clock is too high, all 4 loops will eventually fail, therefore the traces will show 4 repeated patterns of:
1. How often the callback function which was configured by zn_uart_register_rx_callback() API will ba called?
This is called for every time the MCU UART RX interrupt is invoked. For this reason, it is extremely important that is callback is lightweight. All heavy processing should be deferred to a thread context.
2. The number configuring by zn_event_enable_irq_events() is not clear.
This configures the number of events that can be queued from the IRQ context.
A configuration of 8 allows for events to be queued from the UART RX callback. i.e. zn_event_issue(my_handler, NULL, ZOS_EVENT_FLAG_FROM_IRQ) can be invoked up to 8 times (without my_handler executing in-between) before the API fails with an overflow error.
3. The meaning of flag used by zn_event_issue() is unclear.
This tells the API that the event_handler is being issued from an IRQ context.
Effectively, this flag tells the API to add the handler to the IRQ handler queue configured with zn_event_enable_irq_events().
4. The relation between the data size specified by zn_uart_receive_bytes() and timeout. If the timeout occurred, will the data be received until the timeout occurred? Or, will the whole data discarded? If the former is the case, can we know the actually received size by zn_uart_get_bytes_received()?
If zn_uart_receive_bytes() returns ZOS_TIMEOUT, then the amount of data read up until the timeout is returned.
zn_uart_get_bytes_received() contains the amount of read data returned in the buffer.
The WAKE pin is an output from the module, and have to be be used to wake the module from sleep state. Connect WAKE to RESET_N using a 1k resistor to enable sleep/wake functionality.
The operation of wakeup is that once sleep timer expires, it triggers the wake pin (which is tied to the reset pin) which resets the module. This is the only way AMW007 wakes itself up. There is no other modes of sleep.
This connection is not required if sleep/wake functionality is not used, or a host MCU has explicit control of the RESET_N pin.
Issuing 'reboot' command is very similar to resetting the module via RESET pin. Though, there is a couple of differences here:
1. RESET_N is tied to the MCU hardware signal. When the pin is assert the MCU is immediately reset, there is no software intervention. While the 'reboot' command will bring down the network (close open stream and disassociate from WLAN/disconnect softap client) and cleanup any running hardware (e.g. stop PWMs, ADCs) before performing a software reset of the MCU.
2. Toggling the RESET_N pin does not cause any text output on the serial bus, whereas issuing a 'reboot' command prints the version string.
In ZentriOS, a default configuration file is a CSV file containing a list of ZentriOS settings.
The default configuration file MUST be named: default_config.csv for ZentriOS to automatically load the settings file after an OTA or a factory reset.
ZentriOS loads the file settings when:
an OTA is successfully completed
the factory reset GPIO is asserted for 5s
The command load default_config.csv is issued. In this case, any config file can be specified as the argument to load.
When the default_config.csv is applied after an OTA, a 'soft' factory reset is done:
Resets NVM flash
Loads factory default values from firmware into Configuration RAM
Loads variable values stored in NVM Backup into Configuration RAM
Loads platform specific settings from OTP memory into Configuration RAM
Loads variable values from the default_config.csv file into Configuration RAM
Saves Configuration RAM to NVM flash
The reset is done so the device is in a known state before the default config is applied: That means once default config is applied, all the variables set in NVM are erased, except the critical setting that are backed up. A list of backed up settings may be found here:
Typically if you want to use a WSTK to program an external device you can change the Debug Mode using Simplicity Studio. However if you're only working with WGM110 and no other Silicon Labs product which requires Simplicity Studio installation you can change the Debug Mode with (and old version) of Simplicity Commander within the WGM110 SDK.
The commander executable is located in C:\SiliconLabs\WizardGeckoSDK\WGM110-1.0.1\bin\commander and you can change the Debug Mode by selecting "Kit" on the left-hand side.
Q: Why is the WF121/WGM110 throughput lower when the module is in AP mode?
A: When WF121/WGM110 is in AP mode it must re-transmit multicast traffic coming from any of its clients. The multicast traffic has to be sent right after a beacon and until it is sent all the unicast TX traffic is blocked.
If there is on-going TCP communication this can cause lost frames, forcing the TCP to re-transmit and decreasing the throughput. This is mostly observable when the clients are Windows/MAX/Linux PCs which use multicast traffic for service discoveries and other purposes.
Also multicast sent from the module itself (by the application) causes the same behavior, not just re-transmitting multicast coming from the clients.
On Windows this can be improved by disabling some of the native discovery services as shown below if they are not required.
Wi-Fi Knowledge Base
KBA: WF200 Drivers and Firmware download
WF200 Drivers and Firmware are available from Github
For Linux applications
Driver: https://github.com/SiliconLabs/wfx-linux-driver
Firmware: https://github.com/SiliconLabs/wfx-firmware
Tools: https://github.com/SiliconLabs/wfx-linux-tools
For RTOS Applications
Driver & Firmware: https://github.com/SiliconLabs/wfx-fullMAC-driver
Tools: https://github.com/SiliconLabs/wfx-fullMAC-tools
Linux Kernel events tracing
Linux Kernel events tracing
When working on a Linux system, it can be convenient to use the kernel events tracing mechanism, (described in details in Documentation/trace/events.txt in the Linux kernel sources).
We will only focus on a very simple use case here.
Listing possible event traces
All traceable events are listed under the /sys/kernel/debug/tracing/events/ hierarchy of directories
Typical result:
The first step is obviously to identify the events you want to trace within these.
For example, let's look at the mmc events structure:
The following hierarchy is present, with files and subfolders:
Each folder containing an enable file can be activated/de-activated by writing a 1 or a 0 to the corresponding enable file.
Each filter file corresponds to a list of filters applied to the corresponding event.
Each format file lists all possible parameter (which can be used in filters) and shows the print format for the corresponding trace.
Event traces format
format files list all possible parameters and show the print format:
Enabling/disabling event traces
To enable mmc/mmc_request_done:
To disable mmc/mmc_request_done:
Filtering events
Filtering events is done by writing a filter to the filter file
Filters can be set on each parameter listed in the format file, whether it is a numeric
or a string
or a combination
Clearing filters
Following event traces during execution
Following this, any enabled event will be traced into the console
Linux SDIO detection
Linux SDIO part detection on the SDIO bus
Under Linux, SDIO parts are bound to the Linux mmc bus.
Before using a Wi-Fi part connected to the SDIO bus of a Linux system, it is necessary that the system detects the HW on the bus. Linux systems will try to detect SDIO parts on the bus at boot, and every time the mmc bus is bound. The latter is what we will use to trace mmc messages related to SDIO detection.
SDIO Detection message
The following message should be visible in dmesg once boot is complete:
one-line check:
Until this message is present in dmesg, it is useless to try to load the driverIf this message is not found, it is necessary to debug SDIO detection, going through the following steps:
These steps are detailed below.
Retrieving the current device tree
Making sure SDIO is enabled in Device Tree
In order for the Linux system to try detecting a part on the SDIO bus, it needs to be part of the Device Tree used at boot.
one-line check (SDIO pins selection):
sdio_pins = "/soc/gpio@7e200000/sdio_pins"; sdio_pins {If this returns an empty line, SDIO detection is not even triggered. Refer to your system documentation to know how to add SDIO to the device tree.
Checking which mmc bus is used for SDIO
one-line check (SDIO mmc bus selection):
If this returns an empty line, SDIO is not connected to any mmc bus. Refer to your system documentation to know how to add SDIO to the device tree.
Checking the mmc bus commands during the SDIO detection phase
This is the trickiest part, since it involves tracking message normally issued at boot, when the system is attempting SDIO detection.
In reality, these are issued every time the mmc bus is bound to the system, so unbinding/binding the mmc bus will trigger a new detection attempt. We use this to avoid activating the traces at boot time, since this is not easy to do.
Preparing the kernel event traces (to be executed with root privileges):
Activating mmc request traces:
Not tracing mmc CMD53 (once working in high-speed mode, to avoid being overloaded with traces once detected):
Tracing the kernel events on mmc1 (adapt the mmc to your own use case):
Typical traces (limited view due zooming on 'cmd_opcode' due to extra long lines):
Stopping mmc request traces (once the traces have been retrieved):
This step is necessary to stop tracing, which is otherwise still active. No additional traces are shown because SDIO traffic only uses CMD53 once detection is complete, and CMD53 are filtered out. It is better to stop tracing completely.
Checking the SDIO detection result
If detection is correct, the 'mmcX new high speed SDIO card at address 0001' message is present in dmesg.
Otherwise, check for errors related to the mmc item corresponding to your part.
SDIO pins used for the detection phase
The SDIO detection as shown above only uses SD_CMD and SD_CLK pins, and is generally performed with a 400kHz SD_CLK. SD_DAT[3:0] are not used yet, so SDIO detection may succeed even though SD_DAT[3:0] are not properly routed.
Max SDIO speed too high
During the last steps of SDIO detection, the SoC sets the SDIO part to 'high-speed' mode on 4 data bits, then configures its own hardware to the maximum selected SDIO speed (controllable in the device tree) only at the very end of the SDIO detection, after a long series of about 26 CMD52 commands.
In case there are issues related to the max clock speed, the last CMD52 commands will return with 'cmd_err=-110' (which means 'TIMEOUT'), and will be followed by a short burst of about 4 CMD55 commands.
Whenever the SDIO detection loop fails, it is repeated with a slower clock speed (400, 300, 200, 100 kHz, respectively), but is still ending with the max clock. If the max clock is too high, all 4 loops will eventually fail, therefore the traces will show 4 repeated patterns of:
CMD52
CMD52
CMD0
CMD8
CMD5
CMD5
CMD7
CMD52
. . .
CMD52 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110
And dmesg will show:
mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card
In this case, check your device tree documentation to check how to reduce the maximum SDIO clock.
Questions on UART event configuration using ZentriOS API/SDK
1. How often the callback function which was configured by zn_uart_register_rx_callback() API will ba called?
This is called for every time the MCU UART RX interrupt is invoked. For this reason, it is extremely important that is callback is lightweight. All heavy processing should be deferred to a thread context.
2. The number configuring by zn_event_enable_irq_events() is not clear.
This configures the number of events that can be queued from the IRQ context.
A configuration of 8 allows for events to be queued from the UART RX callback. i.e. zn_event_issue(my_handler, NULL, ZOS_EVENT_FLAG_FROM_IRQ) can be invoked up to 8 times (without my_handler executing in-between) before the API fails with an overflow error.
3. The meaning of flag used by zn_event_issue() is unclear.
This tells the API that the event_handler is being issued from an IRQ context.
Effectively, this flag tells the API to add the handler to the IRQ handler queue configured with zn_event_enable_irq_events().
4. The relation between the data size specified by zn_uart_receive_bytes() and timeout. If the timeout occurred, will the data be received until the timeout occurred? Or, will the whole data discarded? If the former is the case, can we know the actually received size by zn_uart_get_bytes_received()?
If zn_uart_receive_bytes() returns ZOS_TIMEOUT, then the amount of data read up until the timeout is returned.
zn_uart_get_bytes_received() contains the amount of read data returned in the buffer.
SLEEP and WAKE operation for Zentri Wi-Fi module AMW007/AMW037
The only way to wake-up the AMW037/AMW007 module is when the timer expires. Once module sleeps, it will wakeup once system.wakeup.timeout expires. More here:
https://docs.zentri.com/zentrios/wl/latest/cmd/commands#sleep
https://docs.zentri.com/zentrios/wl/latest/cmd/variables/system#system-wakeup-timeout
The WAKE pin is an output from the module, and have to be be used to wake the module from sleep state. Connect WAKE to RESET_N using a 1k resistor to enable sleep/wake functionality.
The operation of wakeup is that once sleep timer expires, it triggers the wake pin (which is tied to the reset pin) which resets the module. This is the only way AMW007 wakes itself up. There is no other modes of sleep.
This connection is not required if sleep/wake functionality is not used, or a host MCU has explicit control of the RESET_N pin.
For AMWxxx family (ZentriOS), what is the difference between RESET_N pin and reboot command?
Issuing 'reboot' command is very similar to resetting the module via RESET pin. Though, there is a couple of differences here:
1. RESET_N is tied to the MCU hardware signal. When the pin is assert the MCU is immediately reset, there is no software intervention. While the 'reboot' command will bring down the network (close open stream and disassociate from WLAN/disconnect softap client) and cleanup any running hardware (e.g. stop PWMs, ADCs) before performing a software reset of the MCU.
2. Toggling the RESET_N pin does not cause any text output on the serial bus, whereas issuing a 'reboot' command prints the version string.
Managing your NVM variables in ZentriOS
Default Configuration File
In ZentriOS, a default configuration file is a CSV file containing a list of ZentriOS settings.
The default configuration file MUST be named:
default_config.csvfor ZentriOS to automatically load the settings file after an OTA or a factory reset.ZentriOS loads the file settings when:
an OTA is successfully completed
the factory reset GPIO is asserted for 5s
The command load default_config.csv is issued. In this case, any config file can be specified as the argument to load.
When the default_config.csv is applied after an OTA, a 'soft' factory reset is done:
Resets NVM flash
Loads factory default values from firmware into Configuration RAM
Loads variable values stored in NVM Backup into Configuration RAM
Loads platform specific settings from OTP memory into Configuration RAM
Loads variable values from the
default_config.csvfile into Configuration RAMSaves Configuration RAM to NVM flash
The reset is done so the device is in a known state before the default config is applied: That means once default config is applied, all the variables set in NVM are erased, except the critical setting that are backed up. A list of backed up settings may be found here:
https://docs.zentri.com/zentrios/w/latest/configuration-and-setup#nvm-backup-variables
In case developer is using ZentriOS SDK to write his own native app, to keep configurations safe across resets it is recommended to:
1) Convert all the settings in default_config.csv to 'application settings':
https://docs.zentri.com/zentrios/wz/latest/sdk/development/settings-and-resources#application-settings
2) Remove the default_config.csv from the bundle
3) On ZAP startup, check if the default_config.csv exists and delete it if so. This ensures the old default_config is not applied on the next OTA
The default_config.csv is largely intended for non-ZAP applications. Storing the settings as 'application settings' will achieve the same effect.
What's the reflow profile for the WF111 module?
WGM110: Setting the WSTK in Debug Out Mode without Simplicity Studio
WF121/WGM110: Throughput in AP mode