i_doSysSync() – di-ce.de

Description

i_doSysSync() runs the update process as explained further down and here: OTA – Considerations and Requirements. In most cases the function can be used in its simplest form. It only needs a HTTP_Client instance and internet connectivity. This function should be called regularly so that it can manage the required processes in the background. It handles the polling interval automatically so that it only gets active at the first start and in the given intervals.

v_SysSync_RestartInterval() resets the polling interval, so that the server will be accessed at the next call of i_doSysSync() straight away. Use this function for example after sleep(), so that after each system wakeup the server will be accessed and polled for pending updates.

Syntax

i_doSysSync( opt_HTTP_Client ); – using default values: Polls server at start and then every 15 min.; transfers positioning information and uses the server-URL and device credentials as stored in the bootloader settings during device registration (via diceConfig-tool).

i_doSysSync( opt_HTTP_Client, ou32_interval, ob_sendPosition, s_Account, s_Server );

Parameters

HTTP_Client* opt_HTTP_Client – pointer to an instance of class HTTP_Client (e.g. WiFiHTTPClient)
uint32_t ou32_interval – polling interval in [ms] (default: 15min = DEFAULT_UPDATE_INTERVAL). Note that the internal counter uses the millis() function and not any RTC timing. This means that sleep() periods don’t count for the interval ( see also v_SysSync_RestartInterval() above).
bool ob_sendPosition – default true; if true, the process transmits the current location (if available) to the update server.
String s_Account – default: “” ; pre-definition of a static SysSync user account (eg, ‘myName@di-ce.de’) for automatic registering of the device. It is recommended to assign the device with the diceConfig tool to a account instead; and omit s_Account (“”) in this function call.
String s_Server – default: “” : uses the server URL of the SysSync server stored in the bootloader setting. It is pre-set to ‘syssync.di-ce.de’ by default and set during registration (diceConfi-tool).

Returns

int:
0: SYSSYNC_RET_IDLE – nothing to do (system is up to date or it is not yet time to do anything, internet not required)
1: SYSSYNC_RET_INET_DEMAND – internet required. The main application should establish internet connection (eg. WiFi.begin())
2: SYSSYNC_RET_UPDATE_WARN – update warning – the SysSync process will modify the SerialFlash filesystem (erase it, delete files etc.) from now on. This means that the main application must not access it anymore.
3: SYSSYNC_RET_PROCESSING – the update process is in progress. This means for the main application: keep internet connection up; the SerialFlash file system must not be accessed.
4: SYSSYNC_RET_RESET_WARN – restart warning – the main application shall disconnect from the internet connection and prepare for a reset that will be triggered with the next call of the i_doSysSync() function.

-1: SYSSYNC_RET_ERROR_CREDENTIALS – device credentials are not available or not accepted by the server.
–2: SYSSYNC_RET_ERROR_SERIALFLASH – error accessing the SerialFlash file system

Example Code

This example can be used on a dice-WiFi and shows how an application reacts on the return value of i_doSysSync().

#include "SysSync.h"
#include <WiFiNINA.h>
char ssid[] = "mySSID";
char pass[] = "myPass";

WiFiHTTPClient t_postClient;


void setup()
{
	Serial.println("STARTUP: "+BOOTLOADER_SETTING.s_get_app_name()+" (V" + BOOTLOADER_SETTING.u32_get_app_version()+")");
}

void loop()
{
  int	i_ret = i_doSysSync(&t_postClient);
  if( (i_ret == SYSSYNC_RET_INET_DEMAND) && (WiFi.status() != WL_CONNECTED) )
  {
    Serial.println("Establishing WiFi connection");
    WiFi.begin(ssid, pass);
  }
  if( (i_ret <= SYSSYNC_RET_IDLE) && (WiFi.status() == WL_CONNECTED) )
  {
    Serial.println("Shutdown WiFi connection");
    WiFi.disconnect();
  }
  if( i_ret >= SYSSYNC_RET_UPDATE_WARN ) // if an update is in progress then do only this
  {
    Serial.println("Update in progress...");
    while( (i_ret = i_doSysSync(&t_postClient)) >= SYSSYNC_RET_UPDATE_WARN ) yield(); 
  }
  if( i_ret == SYSSYNC_RET_RESET_WARN )
    Serial.println("Resetting");
}

^{see example ‘File -> Examples -> SysSync->SysSyncWiFi}

More insight: SysSync update process steps:

Checks the polling interval time
Gets the server-URL and device-credentials (eg. from bootloader settings)
Connects to the syssync-server (limited times and in retry-intervals only)
Authenticates itself to the server
Delivers the current system information (current app. + version, file system content and position (if configured)).
Fetches the new update job information from the server (if a job is pending)
Compares the current system to the update job configuration
Warns the application that an update is about to be processed (so that the application can finish accessing the serial flash any further)
Downloads necessary app and files (+ file validation)
Prepares an image of the current application (for recovery in case the new app. fails)
Warns the application that a reset will come next (so that the appl. can shutdown the internet connection etc.)
Resets the device
The bootloader now installs the new application
The new application starts and calls the i_doSysSync() process again, which
Reports the current (new) system configuration to the server
If the new configuration (app+files) matches the desired update on the server then the job is finished and the previously prepared recovery image will not be used.
If the new application fails to connect to the server then the bootloader will re-install the previous application image when the device is restarted (e.g. powered off/on or reset) again.

Notes and Warnings

There are further examples in the Arduino IDE Example menu that demonstrate how to include the SysSync + CANIP provider functions for dice-WiFi, ETH, IoT in a regular application (could be used as a template for new projects). Another example (SysSyncCANIP.ino) reports the process steps and states of the SysSync process in more details and could be used to test and learn more about the update process in general.