~uplink

~uplink:

Comfortable automatic control of uplink interface.

The device knows two operation modes:

WAITING / PROG - when mandatory setup data (or timebase) is not available yet (typ. after very first set into operation)
The device tries to connect to it's backend and get the required data.
Entering this state is optional any may occur immediately after boot only. It's indicated by UPLINK_EV_WAITING.
NORMAL - regular application operation
Entering this state is indicated by UPLINK_EV_READY.

Do NOT use µINO's watchUplinkConfig() together with this library!

Recommended (but not mandatory) to be used together with ~dde library.

Using UPLINK_ONLINE mode

In this mode, the device tries to recover from broken uplink fully automatically according to this sequence:

Broken uplink detected → onUplinkEvent( UPLINK_EV_ONLINE_BROKEN)
Wait endlessly until
- Uplink recovered → onUplinkEvent( UPLINK_EV_ONLINE_OK)
- Time uplinkMode.onlineRetrySeconds expired → issue uplinkFlush() and onUplinkEvent( UPLINK_EV_ONLINE_DIAL)

Example - DDE

// sample UPward config container #config0 up1 up f1 u8 // sample DOWNward config container #config9 down1 down f9 u8

Example - DLO

// --- UPward config containers --- new up1_[DDE_up1]; // = [...] optionally set safe defaults other than 0 public onUplinkRestore_up1() { if (DDE_up1_read( up1_)) return; // abort on error .. process up1_ } // --- DOWNward config containers --- new down1_[DDE_down1]; public onUplinkApply_down1() { if (DDE_down1_read( down1_)) return ERROR; // abort on error .. apply down1_ after successful read return OK; } // --- dispatch uplink events --- public onUplinkEvent( ev, param) { switch( ev) { // application run --- downward configs available - switch app into NORMAL operation case UPLINK_EV_READY: { #log( "~uplink-ready"); // start applications regular operation such as a main loop setInterval( appLoop, 1000); // start applications regular operation // optionally use uplinkFlush() and uplinkMode() from here on } // application held during boot // waiting for configs from backend - switch app into HOLD operation case UPLINK_EV_WAITING: #log( "~uplink-waiting (needs x%x)", param); // UPLINK_ONLINE connection changed it's status case UPLINK_EV_ONLINE_OK : signalUplinkOnline( "ok"); case UPLINK_EV_ONLINE_BROKEN: signalUplinkOnline( "broken", param); case UPLINK_EV_ONLINE_DIAL : signalUplinkOnline( param ? "dial-recover" : "dial-boot", param); // default: ignore any other event } } #callback appInit() { uplinkInit( UPLINK_ONLINE); } main() { salve( appInit); }

UPLINK_DBG -

activate debug outputs of uplink library

Must be set in DDE (e.g. ahead of DLO)

#define UPLINK_DBG 1

uplinkOptions:

global options

onlineRetrySeconds : s32 = 60*60 - for UPLINK_ONLINE mode only;

Time to wait from uplink broken detection (UPLINK_EV_ONLINE_BROKEN) until next retry (UPLINK_EV_ONLINE_DIAL)

0 = turn off automatic retry

onlineResyncSeconds : s32 = 24*60*60 - for UPLINK_ONLINE mode only;

Time to periodically force resync with backend

0 = turn off automatic resync

ltemNbiotSwitching : s32 = 1 - for UPLINK_ITF_GSM Interface only;

0/1 = Disable/Enable automatic LTE-M/NB-IoT switching for supported modems

Example

uplinkOptions.onlineRetrySeconds= 90; // turn to 90s uplinkOptions.onlineResyncSeconds= 3600; // turn to 1h uplinkOptions.ltemNbiotSwitching= 0; // disable automatic LTE-M/NB-IoT switching

TuplinkItf: s32

Selectable uplink interfaces

UPLINK_ITF_UNKNOWN = -1 - Uplink interface not selected yet. Use uplinkInit(), uplinkSetItf(), uplinkSetItf_GSM(), uplinkSetItf_WIFI() or uplinkSetItf_LAN() to select the uplink interface.

UPLINK_ITF_NONE = 0 - No uplink, communication with the server not possible

UPLINK_ITF_GSM = 1 - Mobile network modem

UPLINK_ITF_WIFI = 2

UPLINK_ITF_LAN = 3

uplinkGetItf()

get currently used uplink interface

returns : TuplinkItf

uplinkSetItf(itf)

Switches the uplink interface to the transferred interface and applies the last known configuration

This function uses the interface configuration as currently preset in the registry.

It is not possible to use the WiFi interface simultaneously for the uplink and for communication with sensors (i.e. uplinkSetItf(UPLINK_ITF_WIFI) and WiFi_Init() cannot be used together). If both functions are required, WiFi_Close() must always be called before uplinkSetItf(UPLINK_ITF_WIFI) and uplinkSetItf(UPLINK_ITF_NONE) before WiFi_Init().

Activates the given interface, then

Tries immediately to reconnect using the new interface when UPLINK_ONLINE is active

itf : TuplinkItf - Uplink interface to be activated

returns : s32

OK - The uplink interface was successfully changed

ERROR_TXITF - Uplink interface not available (e.g. not opened, currently closing)

ERROR - If one of the following error occurs

The selected communication interface is not supported by the device

Another error occurs

uplinkSetItf_GSM(), uplinkSetItf_LAN(), uplinkSetItf_WIFI()

rM2M_TxSelectItf

uplinkSetBackupItf(const itf)

Sets backup interface to automatically switch to, in case sync with current interface fails. Return to original interface has to be done in application code.

itf : TuplinkItf - Uplink interface to be used as backup. Use UPLINK_ITF_NONE to disable switching.

returns : s32

OK - The backup uplink interface was successfully set

ERROR - Interface invalid

uplinkSetItfParam_WIFI(ssid, pwd, ?sec, ?ipcfg, ?region)

Sets WIFI interface configuration without switching to interface

// use custom credentials (and store them to registry) uplinkSetItf_WIFI( "TRAINING", "micro-training");

If specified, ssid and pwd are persisted to APP_FLASH via registryWrite_WIFI().

ssid : astr

"TRAINING" - ssid

pwd : astr

"Password-training" - any password

sec : TRegWifiSecurity - optional; defaults to WIFI_SEC_AUTO

ipcfg : astr - optional; → registryWrite_WIFI()

region : astr - optional; → registryWrite_WIFI()

registryWrite_WIFI

uplinkSetItfParam_LAN(ipcfg)

Sets LAN interface configuration without switching to interface

// use custom settings (and store them to registry) uplinkSetItf_LAN( "DHCP");

If specified, ipcfg is persisted to APP_FLASH via registryWrite_LAN().

ipcfg : astr - optional; → registryWrite_LAN()

registryWrite_LAN

uplinkSetItf_GSM()

Switches the uplink interface to mobile network modem

This is the default interface after power on.

Tries immediately to reconnect using the new interface when UPLINK_ONLINE is active.

returns : s32

OK - The uplink interface was successfully changed to mobile network modem

ERROR_TXITF - Uplink interface not available (e.g. not opened, currently closing)

ERROR - If one of the following error occurs

The GSM communication interface is not supported by the device

Another error occurs

uplinkSetItf_WIFI(), uplinkSetItf_LAN(), uplinkSetItf()

rM2M_TxSelectItf

uplinkSetItf_WIFI(?ssid, ?pwd, ?sec, ?ipcfg, ?region)

Switches the uplink interface to WIFI and optionally sets the WIFI configuration

// use predefined credentials from registry uplinkSetItf_WIFI(); // use custom credentials (and store them to registry) uplinkSetItf_WIFI( "TRAINING", "micro-training");

If specified, ssid and pwd are persisted to APP_FLASH via registryWrite_WIFI().

Tries immediately to reconnect using the new interface when UPLINK_ONLINE is active.

Fallback mechanisms, such as using the GSM interface, can be set using uplinkSetBackupItf().

It's recommended to run this call before uplinkInit().

It is not possible to use the WiFi interface simultaneously for the uplink and for communication with sensors (i.e. uplinkSetItf(UPLINK_ITF_WIFI) and WiFi_Init() cannot be used together). If both functions are required, WiFi_Close() must always be called before uplinkSetItf(UPLINK_ITF_WIFI) and uplinkSetItf(UPLINK_ITF_NONE) before WiFi_Init().

ssid : astr - optional

undefined - use preprogrammed value from APP_FLASH.wifiSSID

"TRAINING" - ssid

These parameters apply only if ssid given

pwd : astr - mandatory if ssid given

undefined - use preprogrammed value from APP_FLASH.wifiPwd

"Password-training" - any password

sec : TRegWifiSecurity - optional; defaults to WIFI_SEC_AUTO

ipcfg : astr - optional; → registryWrite_WIFI()

region : astr - optional; → registryWrite_WIFI()

returns : s32

OK - The uplink interface was successfully changed to WIFI

ERROR_TXITF - Uplink interface not available (e.g. not opened, currently closing)

ERROR - If one of the following error occurs

The WIFI communication interface is not supported by the device

Another error occurs

uplinkSetItf_GSM(), uplinkSetItf_LAN(), uplinkSetItf()

rM2M_TxSelectItf

uplinkSetItf_LAN(?ipcfg)

Switches the uplink interface to LAN and optionally sets the LAN configuration

// use predefined credentials from registry uplinkSetItf_LAN(); // use custom settings (and store them to registry) uplinkSetItf_LAN( "DHCP");

If specified, ipcfg is persisted to APP_FLASH via registryWrite_LAN().

Tries immediately to reconnect using the new interface when UPLINK_ONLINE is active.

Fallback mechanisms, such as using the GSM interface, can be set using uplinkSetBackupItf().

It's recommended to run this call before uplinkInit().

ipcfg : astr - optional; → registryWrite_LAN()

returns : s32

OK - The uplink interface was successfully changed to LAN

ERROR_TXITF - Uplink interface not available (e.g. not opened, currently closing)

ERROR - If one of the following error occurs

The LAN communication interface is not supported by the device

Another error occurs

uplinkSetItf_GSM(), uplinkSetItf_WIFI(), uplinkSetItf()

rM2M_TxSelectItf

TuplinkMode: s32

UPLINK_TRIG - interval mode, connect with backend only upon uplinkFlush() and disconnect afterwards

UPLINK_WAKEUP - same as above, but allow backend to wake up the device anytime

UPLINK_ONLINE - connect immediately with backend and stay online

Tries to recover from broken uplink automatically as specified by uplinkOptions.onlineRetrySeconds.

UPLINK_NOPOS - optional flag, do NOT fetch position information before dialing

uplinkInit(mode, forceOnce=0)

starts fully automatic uplink control:

The uplink interface is automatically set to mobile network modem (UPLINK_ITF_GSM, see TuplinkItf), if not explicitly set by using uplinkSetItf(), uplinkSetItf_GSM(), uplinkSetItf_WIFI() or uplinkSetItf_LAN() before calling uplinkInit().

fire onUplinkRestore_xxx() for all UPward configs to (optionally) get last sent status from local storage
fire onUplinkApply_xxx() for all DOWNward configs to recover last known settings from local storage or use safe fallback values
while not all DOWNward configs yet available locally, mark application to be in waiting / prog operation
1. fire onUplinkEvent( UPLINK_EV_WAITING) once
2. fire onUplinkApply_xxx() for each DOWNward config comming in from backend
turn uplink into mode specified by uplinkInit()
fire onUplinkEvent( UPLINK_EV_READY) - run app in regular operation
From here on you may use uplinkMode(), uplinkFlush() and DDE_xxx_write() operations.
the application is now in normal operation
- fire onUplinkApply_xxx() for all DOWNward configs upon changes from backend
- fire onUplinkEvent( UPLINK_EV_ONLINE_xxx) when status of UPLINK_ONLINE connection changes

mode : TuplinkMode - uplink mode to use when regular app operation starts

forceOnce - connect to backend once, either due to UPLINK_EV_WAITING, or at least as soon as UPLINK_EV_READY appears.

Combines with mode UPLINK_TRIG and UPLINK_WAKEUP only.

uplinkMode(mode=-1)

get and/or change operation mode of uplink

Ignored during uplink initialisation phase, applies after UPLINK_EV_READY only.

Moving apart from UPLINK_ONLINE drops the line immediately

Moving towards UPLINK_ONLINE starts dialing immediately, but returns before uplink is established

mode : TuplinkMode - optional; when given, changes uplink mode (only if mode is not already set)

returns : TuplinkMode - current uplink mode UPLINK_xxx (w/o UPLINK_NOPOS flag)

uplinkFlush(?flags)

trigger immediate sync with backend

Intended use with modes UPLINK_TRIG and UPLINK_WAKEUP.

Has usually no effect when in mode UPLINK_ONLINE, despite if the uplink is currently broken.

flags : TrM2M_TxStart - optional; overrides default behaviour given with updateInit() (e.g. UPDATE_NOPOS)

returns : Terror

OK - If successful

ERROR_SIM_STATE - If a connection is not possible due to the current SIM state, see TRM2M_SIM_STATE

ERROR_MODEM_DISABLED - If the connection cannot be established due to the supply voltage being too low

ERROR_TXITF - If the connection cannot be established due to the TX interface configuration (e.g. TX interface not open)

<OK - If another error occurs - see Terror

uplinkStatus(flags=0)

dump any changes of uplink status/RSSI/interface to console and return uplink status

Simply call this function regularly to keep track of the uplink status via console.

#callback pollUplinkStatusAndSayHelloWhenChanged() { static status_; if( changed( status_, uplinkStatus())) { #log( "hallo! %04x", status_); } } appInit() { setInterval( pollUplinkStatusAndSayHelloWhenChanged, 1000); }

flags : s32

UPLINK_STATUS_NODUMP - shorthand for UPLINK_STATUS_NOLOG | UPLINK_STATUS_NOWATCH

UPLINK_STATUS_NOLOG - do not dump to console

UPLINK_STATUS_NOWATCH - do not dump to watches

returns : TrM2M_TxStatus - same as returned by rM2M_TxGetStatus()

uplinkGetSimState()

Returns the state of the SIM chip

The function can be used to check if a connection to the server is permitted.

returns : s32

TRM2M_SIM_STATE - Current SIM state

ERROR - If an error occurs

uplinkErrorToStr(err)

get description of error code

err : TrM2M_TxError - value as supplied by rM2M_TxGetStatus( err)

TuplinkEvent: s32

uplink events

UPLINK_EV_READY - uplink ready, regular app operation can start

All DOWNward configs are locally available.

It's mandatory to handle this event inside onUplinkEvent().

UPLINK_EV_WAITING - uplink not ready yet, switch app into WAITING/PROG operation

At least one DOWNward config is not locally available during boot, the device is waiting to receive config(s) from server.

Therefore the UPLINK_ONLINE mode is temporarly activated (and held) automatically.

UPLINK_EV_ONLINE_DIAL - uplink dialing (not issued while waiting)

UPLINK_EV_ONLINE_OK - uplink established successfully (not issued while waiting)

UPLINK_EV_ONLINE_BROKEN - uplink lost (not issued while waiting)

onUplinkEvent(ev, param)

uplink lib signals some important event

Typ. usage for logging and local status signalling.

At least UPLINK_EV_READY must be handled, all other events are optional.

ev : TuplinkEvent

param : s32 - optional parameter, meaning depends on ev:

UPLINK_EV_WAITING - bitmask of missing configs

UPLINK_EV_ONLINE_DIAL - 0 upon boot, or last seen TrM2M_TxError after uplink broken

UPLINK_EV_ONLINE_BROKEN - last seen TrM2M_TxError

others - not used (e.g. 0)

Libraries

~uplink

Description

UPLINK

Using UPLINK_ONLINE mode

Example - DDE

Example - DLO

Example

These parameters apply only if ssid given

On this page

~uplink