Sushi-IoT-Framework Software Manual

This guide refers to the Sushi-IoT-Framework latest firmware versions.

Coding

Sushi-IoT-Framework embeds the MicroPython REPL interface, for coding refer to the Sushi-IoT-Framework coding.

Integrated tasks & components

Sushi-IoT-Framework integrates some common system tasks and software components that can be useful to speed up development.

Task name	Description	Requirements
Wi-Fi	Wi-Fi network connection management	ESP32 chip only
Web interface	Web user interface accessible by a browser	ESP32 chip only
Setup	System setup via configuration file	ESP32 chip only
Log & Events	System log and event register management	ESP32 chip only
System health	Monitor system status. Log traces, store to file, and send device status remotely. Manage status LEDs	- (OPTIONAL) External LEDs - (OPTIONAL) Voltage divider for ADC inputs to read battery level and power status
On-device interface	On-device user interface with screen and keypad	- 4-button keypad - OLED screen
Modem	Modem management to enable high-level functions like sending/receiving SMS, performing HTTP GET/POST	Modem module
Temperature	Manage temperature sensors	Temperature sensor
Data manager	Manage and send data remotely via HTTP POST, switching automatically between Wi-Fi and modem	- (OPTIONAL) Modem

Wi-fi management

The wi-fi management let setup the device to work in 2 ways:

Act as wi-fi access point
Connect to am existing wi-fi network

The setup can be done by the web-interface.

Default network settings

Wi-fi mode: Access point
Network SSID: "Sushi-..."
Network password: ""
IP address: 192.168.1.100

Extra functions

It is always possible to force the Wi-Fi to run in access point mode by holding the designated button for about 15 seconds: after that time the Wi-Fi will switch to access point mode. So hold the button pressed and after 15-20 seconds scan the local Wi-Fi networks: you should detect the "Sushi-IoT" network. Note that this does not permanently reset the device to factory settings: it only forces Wi-Fi to start in AP mode with default network settings (IP address 192.168.1.100 and no password).
At the next micro reboot (reset button pressed or power off), Wi-Fi will start again according to the saved configuration.
The specific button depends on the CPU board:
- ESP32DevKitC board: use the onboard "BOOT" button (looking at the ESP32 board with USB connector in the bottom, it is the button on the right).
The system parameter powersave_time_wifi_off_min defines the timeout (in minutes).
If the device cannot connect to the configured Wi-Fi network (or, in AP mode, no client is connected) for longer than this time, the wireless hardware is switched off to save energy.
Reconnection can then be done either by restarting the device or using the on-device interface.

Web interface

The web interface is divided into the following sections:

SETTINGS: contains all system settings
STATUS: displays system information

Access is protected by user levels with 3 profiles. HTTPS is supported (default is HTTP).

Default users

User name	Grants	Default password
user	Read-only access	"1234"
admin	Read-write access with some limitations	"2801"
root	Full read-write access including system updates	"1976"

System setup

The Sushi-IoT Framework can be configured either through the web interface or via the MicroPython REPL interface.
Basic settings are available as user controls directly in the web interface, while all settings (both basic and advanced) can be managed through a configuration file.
This configuration file can be saved or loaded from the web UI using the controls at the bottom of the Settings section, and it can also be accessed from the MicroPython file system and API.

Factory restore

If you lose Wi-Fi connection and just need to access the web UI, you can force AP mode by pressing the dedicated onboard button (see Wi-Fi extra functions).
A full factory restore can be performed by sending a command from the MicroPython REPL, see Sushi-IoT-Framework coding.

Log & Events

System log and events can be useful to monitor & debug the system working. Both can be accessed by the web-interface in the status page. Log can be enabled even from the MicroPython REPL interface. Logs are cleared at every system restart while events are stored into a file. The max events file size is defined by the configuration parameter event_register_size_kb.

System health & monitor

System health is a component useful to monitor the device status in different ways:

Read the battery level and main power supply status. Require to connect battery and power to 2 ADC input with proper external resistor divider. For pinout details see Sushi-board or your board hardware manual. Configuration parameter: battery_enable
Trace to log the system status (configuration parameter system_info_log_frequency_min).
Store to file the system status (configuration parameters system_info_store_frequency_min and system_info_csv_filter).
Send remotely the device status by http POST. Useful for example to monitor remotely an IoT device. This function requires setting the parameters system_info_send_http_post_frequency_min (frequency) and http_post_delivery_address (destination).
Manage status LEDs. Let monitor the status by LEDs connected to the device.
- System status: function enabled by system_status_led parameter. 1 slow blink indicates OK, otherwise it's an error state.
- Wi-Fi status: function enabled by wifi_status_led parameter. 1 slow blink indicates client connected; quick continuous blink indicates access point mode; otherwise it's an error state.

On-device interface

This component manages a system menu accessible by a screen and a keypad directly on the device.
Basically the following submenus are present:

Diagnostic: several diagnostic info about the device, like battery level, temperature, etc.
System info: versions and date-time info.
Wi-Fi: Wi-Fi connection status, IP, option to force Wi-Fi off or in access point mode.
Modem: modem status and network info.

Configuration parameters: keyboard_enable, lcd_enable, ioex_enable.

The standard menu management uses a 4 buttons keyboard (keyboard_enable = 4) to navigate: NEXT, PREVIOUS, BACK, ENTER.

The menu can be extended with application specific submenus by Sushi-IoT-Framework coding.

Modem management

Modem management component:

Perform the background tasks to manage the modem by AT commands, including SIM management (PIN, SMS center, APN, etc.). This includes a quite reliable monitor of the modem status, performing all the actions to keep the modem always available and working properly. To achieve maximum reliability, it is recommended to also connect the MOS-controlled modem power control.
Enable the Sushi-IoT-Framework API to easily perform high-level functions like send/receive SMS, perform HTTP GET/POST, and trigger actions when calls from certain numbers are received. See Sushi-IoT-Framework coding.

Anyone who worked on low-level modem management knows how tricky it can be to perform all the required tasks reliably. This component makes common operations quite easy.

Temperature sensor

This component simply manages one or more temperature sensors that can be read in different ways: in the system status, in the user menus, or via Sushi-IoT-Framework coding.
Configuration parameter: ext_temperature_sensor_enable.

Data manager

In an IoT application it is common to have data to send remotely to some server (e.g., sensor data or alarms). This component manages all the tasks:

Send data by HTTP POST.
Put the data into a queue to manage multiple requests simultaneously.
Manage different retries in case of errors.
Try Wi-Fi if available; if not, switch automatically to use the modem (which requires a completely different and tricky management).
Finally, fire a callback to give feedback when the process ends.

The Sushi-IoT-Framework API provides an interface to this component, simplifying the process with minimal effort.
Configuration parameters: http_post_delivery_address, use_wifi_for_http_post.

System parameters

To display a brief list with all parameters from the MicroPython REPL call sushi_utils.list_params(...).

SYSTEM MODULE

>>> sushi_utils.list_params('system')

WIFI MODULE

>>> sushi_utils.list_params('wifi')

Or see the result in Sushi IoT MicroPython quick reference.

Hardware compatibility & pinout

Some of the tasks integrated into the Sushi-IoT Framework manage external hardware, so it's important to know which pins of the microcontroller are used to connect the external devices.

The base platform is always an ESP32 SoC, but the exact pin mapping used to control external peripherals depends on the specific board you're using.
To display a brief table with all board-specific pins, call the sushi_utils.pinout() function from the MicroPython REPL.

Show boards list

>>>sushi_utils.pinout()
  Available boards:
*  ID 0: ESP32-DevKitC on Sushi Board

Show board specific pinout

>>>sushi_utils.pinout(0)  
=== ESP32-DevKitC on Sushi Board ["board_model" ID: 0] ===
...

Or see the result in Sushi IoT MicroPython quick reference.

For more details, refer to your board’s hardware manual:

Sushi-IoT Board: see the Sushi-IoT Board Hardware Manual.
Standalone ESP32-DevKitC board: it uses the same pinout as the Sushi-IoT Board but you have to connect all the external devices yourself .

Issue & Remarks

Differences vs MicroPython

Sushi-IoT-Framework manages some system/hardware tasks, the following table highlights some points to consider during MicroPython scripting.
This table refers to the latest available version of Sushi-IoT-Framework-MicroPython integration: Sushi-IoT-Framework version.

MicroPython module	Remarks
ADC	Disabled. The MicroPython implementation uses an older version of driver that is not compatible with the current Sushi-IoT-Framework ADC management (most recent ESP32 drivers). Reactivate the ADC module is priority one.
Wi-Fi	Sushi-IoT Framework manages Wi-Fi connections with all the most common options. Using the native MicroPython Wi-Fi implementation at the same time would cause a conflict, so to do this you first need to disable Wi-Fi in the Sushi-IoT setup (wifi_mode = 0).

Known bugs

During MicroPython testing some bugs arose. The plan is to update the embedded MicroPython implementation to remove them.

MicroPython known bugs

MicroPython module	Problem
WebREPL	WebREPL is working but it's an experimental feature. During testing, cases were experienced where it completely blocked the microcontroller (requiring a power cycle).
time	time.localtime() function returns the wrong year. Other fields are correct.

Report an issue to mo.iot.wiz@gmail.com