LED Signalling

Description

The library provides an easy way to integrate the Microtronics standard LED signalling (see TBD) into IoT Apps.
This includes the display of operating states (e.g. connection establishment) and error codes via the status LED of the rapidM2M device.

In order to save energy, it is possible to specify the time after which the LED signalling should be deactivated. The library also offers to extend the Microtronics standard LED signalling by your own LED signalling.

Supported devices:

  • rapidM2M C3xx
  • myDatalogEASY IoT/IoTmini
  • rapidM2M T32x
  • rapidM2M M22x
  • rapidM2M M23x

OVERVIEW

led_Abstract:
The library provides an easy way to integrate the Microtronics standard LED signalling (see led_states) into IoT Apps. This includes the display of operating states (e.g. connection establishment) and error codes for the uplink interface. The library uses the status LED of the the rapidM2M device or rapidM2M hardware platform to output the operating states and error codes.
In order to save energy, it is possible to specify the time after which the display of the operating states and error codes should be deactivated (using LED_ResetActiveTimeout()).
For rapidM2M C3xx devices the library additionally signals whether the supply of the rapidM2M C3xx has been switched to the internal rechargeable buffer battery (i.e. a supply voltage failure has been detected).

The library also offers the possibility to extend the Microtronics standard LED signalling by your own LED signalling (using LED_SetAppSpecificState()).
Supported rapidM2M devices:
  • rapidM2M C3xx:
  • Supported rapidM2M hardware platforms:
  • rapidM2M Easy/EasyIoT
  • rapidM2M M2/M23
  • rapidM2M T32x
  • led_states:

    GSM uplink states

    The following GSM uplink signalling LED states are supported.
    Since only a single LED can be connected to the output for the Status LED of the rapidM2M M2/M23 modules, no different colors can be used for LED signalling.

    Error/status blink codes

  • 0x - Transmission OFF
  • 1x green - Last connection OK
  • 2x red - Last transmission faulty
  • 7x red - Network block/no matching provider
  • 8x red - No GSM network
  • 9x red - Incorrect PIN / 1 attempt remaining
  • 10x red - No GPRS connection
  • 11x red - No myDatanet server available
  • 12x red - Faulty SIM chip
  • Operating states

  • Flickering (green) - Establishing connection
  • Lights up (green) - GPRS connection established

  • rapidM2M C3xx

    For the rapidM2M C3xx devices, additionally the following state is signalled by the library.
    Lights up (magenta) - Supply voltage failure (i.e. rapidM2M C3xx supplied via the rechargeable buffer battery)
    led_How_to_use:
    /* Time (sec.) after which control of the LED is passed to the application and the color of the LED is changed every second. */ #define EXAMPLE_SIGNALLING_ACTIVE (60) /* Time (sec.) after which control of the LED is returned to the library so that it can use the LED for signalling the uplink status. */ #define LIBRARY_SIGNALLING_ACTIVE (90) /* Current LED state (counts from 0 to 3) */ static iLedState; /* 1 sec. timer is used for the general program sequence */ #callback MainTimer() { // Counter to delay the example specific LED handling static iCounter = 0; // Increase the counter until the example specific LED handling overrules the LED library // --> This gives the example some time to show the current uplink iCounter++; if(iCounter >= EXAMPLE_SIGNALLING_ACTIVE && iCounter < LIBRARY_SIGNALLING_ACTIVE) { // Issues the current LED state via the console #log("[LED] State: %d", iLedState); // The switch is used to change the color of the RGB LED, based on the current iLedState value switch(iLedState) { case 0: LED_SetAppSpecificState(CO_OFF); case 1: LED_SetAppSpecificState(CO_RED); case 2: LED_SetAppSpecificState(CO_GREEN); case 3: LED_SetAppSpecificState(CO_YELLOW); } // Increases iLedState to switch between different LED states. It is ensured that iLedState does not exceed 3. iLedState = (iLedState + 1) & (0x03); } else if(iCounter == LIBRARY_SIGNALLING_ACTIVE) { // Return LED signalling back to the library LED_UseMicrotronicsSignalling(); // Activate a LED timeout LED_ResetActiveTimeout(20); // Initiate a new connection, to briefly show the LED signalling unitl it is // turned off again by the timeout set with LED_ResetActiveTimeout() uplinkFlush(); } } /** * Function that is called up when the device has been prepared for the start of the application by the * "salve" function. I.e. the device is ready for proceeding with the application. */ #callback AppInit() { // Initialize LED library LED_Init(); // Init uplink and trigger a connection to show the LED signalling for the uplink state uplinkInit(UPLINK_TRIG, true); // Initialisation of a cyclic 1 sec. timer setInterval(MainTimer, 1000); } /* Application entry point */ main() { // Prepare device for the application start salve(AppInit); } /* The following function is not used for this example. However, it must be defined because the "~uplink" library required for the rapidM2M-c3-base library. */ onUplinkEvent(ev,param) { #pragma unused ev, param }

    BASIC

    LED_ERROR_x:

    LED library errors

    LED_ERROR_NOT_INITIALIZED = (-1) - The library is not initialized (call LED_Init() to initialize the library)
    LED_ERROR_ALREADY_INITIALIZED = (-2) - The library was already initialized (i.e. LED_Init() was called twice, without calling LED_Close() in between)
    LED_ERROR_INVALID_TIMEOUT = (-3) - An invalid LED active timeout was provided
    LED_Init(iLedActiveTimeout=-1)

    Initializes LED signalling

    The function first turns off the LED and activates Microtronics standard LED signalling.
    iLedActiveTimeout : s32 - Defines how long the signalling of the different LED states should be active before it is deactivated in order to save energy. [sec]
  • (-1) - Disables the LED active timeout (i.e. LED signalling is permanently active)
  • (> 0) - Enables the LED active timeout (i.e. LED signalling is disabled after the specified timeout expires)
  • returns : s32
    OK - LED signalling was successfully enabled
    LED_ERROR_ALREADY_INITIALIZED - LED_Init() was already called (see LED_ERROR_x)
    LED_ERROR_INVALID_TIMEOUT - iLedActiveTimeout was set to 0 (see LED_ERROR_x)
    LED_Close()

    Disables LED signalling

    The function turns off the LED and disables LED signalling.
    LED_ResetActiveTimeout(iNewTimeout=0)

    Resets the timeout after which the signalling of the different LED states is deactivated.

    The function resets the LED active timeout and overrides the currently configured timeout if desired.
    iNewTimeout : s32 - The new LED active timeout that should be used [sec]
    -1 - Disables the LED active timeout (i.e. LED signalling is permanently active)
    0 - Only reset the LED active timeout. The value specified during LED_Init() or the last call of LED_ResetActiveTimeout() is used for the timeout.
    >0 - Sets the LED active timeout to the passed value and resets the LED active timeout countdown. This value is now used for the timeout if no new value is specified when calling LED_ResetActiveTimeout().

    EXPERT

    LED_SetAppSpecificState(iRGB=CO_OFF, iMode=LED_STATIC, iCount=0, bool:bResetActiveTimeout=false)

    Overrules Microtronics standard LED signalling and sets the LED to the desired state

    This function can be used to extend the Microtronics standard LED signalling by your own LED signalling. The LED is immediately set to the desired state.
    iRGB : Trgb - 0xRRGGBB - 24bit color code, 0=turn off
    See the description of setLed() for information about the RGB colors supported by the different rapidM2M hardware platforms
    For the rapidM2M C3xx devices refer to the description of C3_setLed() for information about the supported RGB colors.
    iMode : s32 - optional
    LED_STATIC - The LED is permanently switched on (default)
    LED_BLINK - The LED is blinking slowly
    LED_FLICKER - The LED is blinking quickly
    LED_FLASH - The LED briefly flashes up cyclically (short on, long off).
    iCount : s32 - optional
    Ignored for mode "LED_STATIC"
    0 - Forever (default)
    Switching back to Microtronics standard LED signalling has to be manually executed by calling LED_UseMicrotronicsSignalling().
    >0 - Number of times the LED should blink, flicker or flash
    The library automatically switches back to Microtronics standard LED signalling after the number of blinks, flickers or flashes have been reached.
    bResetActiveTimeout : bool - Selection whether the timeout, responsible for deactivating the signalling of the different LED states after it has expired, should be reset.
    false - The LED active timeout should not be reset. This means that the current countdown will continue unchanged. (default)
    true - The LED active timeout should be reset
    returns : s32
    OK - Application specific LED signalling was successfully enabled
    LED_ERROR_NOT_INITIALIZED - The library is not initialized (see LED_ERROR_x)
    LED_UseMicrotronicsSignalling(bool:bResetActiveTimeout=false)

    Activates Microtronics standard LED signalling

    The LED switches immediately to the Microtronics standard LED signalling. This means that this function can be used to reactivate the Microtronics standard LED signalling if, for example, the user has activated the permanent output of a user-defined status using the "LED_SetAppSpecificState()" function.
    The LED switches immediately to the Microtronics standard LED signalling.
    bResetActiveTimeout : bool - Selection whether the timeout, responsible for deactivating the signalling of the different LED states after it has expired, should be reset.
    false - The LED active timeout should not be reset. This means that the current countdown will continue unchanged. (default)
    true - The LED active timeout should be reset
    returns : s32
    OK - Microtronics standard LED signalling was successfully enabled
    LED_ERROR_NOT_INITIALIZED - The library is not initialized (see LED_ERROR_x)

    DEBUG

    LED_DEBUG -

    Configure debug mode (see Debug Config)

    0 - No debug outputs
    1 - Output extended debug information (e.g. state of internal timers)
    Debug Config:
    To configure debug mode add the following block to the main.dde file.
    /** * Use this block to configure the debug mode: * * 0: No outputs * 1: Output extended debug information (e.g. state of internal timers) */ #define LED_DEBUG 0

    On this page

    LED Signalling