Libraries

~uplink

Description

Easy to go rapidM2M UPLINK processor

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:
  1. Broken uplink detected → onUplinkEvent( UPLINK_EV_ONLINE_BROKEN)
  2. Wait endlessly until
    • Uplink recovered → onUplinkEvent( UPLINK_EV_ONLINE_OK)
      • or
    • 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
    • Example
    uplinkOptions.onlineRetrySeconds= 90; // turn to 90s
    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().
    1. fire onUplinkRestore_xxx() for all UPward configs to (optionally) get last sent status from local storage
    2. fire onUplinkApply_xxx() for all DOWNward configs to recover last known settings from local storage or use safe fallback values
    3. 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
    4. turn uplink into mode specified by uplinkInit()
    5. fire onUplinkEvent( UPLINK_EV_READY) - run app in regular operation
      From here on you may use uplinkMode(), uplinkFlush() and DDE_xxx_write() operations.
    6. 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)

    On this page

    ~uplink

    GTCT | Imprint | Privacy Policy | Contact