Events, Actions and Timers - icom OS Routers

The Event & Action Handler permits to trigger actions based on the occurrence of an event.

Events

Events are changes of conditions in or at the router that can be used to trigger an action upon their occurrence.

The following events are available at the moment:

  • WAN chain state has changed: A WAN chain has changed its state to online or offline.

  • Interface state has changed: An interface has changed its state to online or offline.

  • Modem state has changed: A modem has changed its state to online, offline, logged in or not logged in (for LTE modems) or sync reached or sync lost (for DSL modems).

  • Signal strength of a modem has changed: The signal field strength has exceeded or fallen below a configured value.

  • Configuration has been changed: The configuration has been changed or activated.

  • Link of an Ethernet port has changed: The link state has changed to UP or DOWN, i.e. an Ethernet cable has be plugged in or out or the connected device has been switched on or off.

  • Container state has changed: An active container has been started or stopped.

  • System restarted: Both, a hardware reset (e.g. power failure) and a software reset (e.g. reset via web interface) are assessed as a restart.

  • Sleep mode has been ended: The sleep mode will be ended after the expiry of the configured length, a reset, a temporary loss of power supply or change of state at one of the inputs. This functionality depends on a certain hardware equipment and is not available for all routers.

  • Auto update succeeded

  • Power source has changed: The voltage applied to the terminals V+1 and V+2 is monitored. The terminal with the higher voltage supplies the device. The event will be triggered, if the higher voltage is now present at the other terminal.

  • Authentication event has been registered: Successful or failed login attempts at the web interface or CLI are detected.

  • Netfilter violation occurred: A netfilter violation occurs, if the IP filters (firewall) reject a packet.

  • Slot device has been restarted: This event will also be triggered with a restart of the router.

  • Digital input has changed: The level of a digital input is now HIGH or LOW or the configured pulse sequence has been counted. The level must be present for at least one second to be detected. A pulse of a pulse sequence must be present for at least 100 ms. A pulse sequence (1-99 pulses) will be closed if the level does not change any more for more than 2 seconds.

  • Analogue input has changed: The level of an analogue input has now exceeded or underrun the configured value.

  • Timer expired: A fix set time has been reached, a countdown has expired or an interval has expired.

  • Counter reached end value: A counter has reached its configured end value.

  • Serial Ethernet state has changed: The TCP connection state of a serial Ethernet gateway has changed to connected or disconnected.

  • SMS has been received: Optionally, a sender phone number and/or SMS text can be specified to determine whether the incoming SMS is considered as an event.

  • MCIP telegram has been received: Optionally, a sender OID and/or telegram content can be specified to determine whether the incoming MCIP telegram is considered as an event.

  • WLAN (Wi-Fi) station state has changed: A WLAN (Wi-Fi) station has changed the state of their connection to an access point to connected oder disconnected.

  • Status of an SFP ports has changed: An SFP module has been inserted into or removed from the respective port.

  • Client certificate obtained from EST server: An EST enrollment has made a new client certificate available on the router.

  • Network tool finished: The selected network tool call has returned the result successful or failed.

Actions

Actions are operations that are started by the router upon the occurrence of an event.

The following actions are available at the moment:

  • Synchronise clock via NTP: The internal clock will be synchronised with the configured NTP server.

  • Restart system: The router will perform a restart.

  • Set INFO LED: The Info LED in slot 2 will be switched on, switched off or start to blink.

  • Send message: The selected message will be dispatched.

  • Start WAN chain: The selected WAN chain will be started.

  • Turn off/on or log out/in modem: The selected modem will either be logged out, logged in, switched off or switched on. If a logged out or switched off modem is used in an active WAN chain,  it will be switched on and logged in again immediately. If it is not part of an active WAN chain, it will first be activated (and logged in), if a WAN chain will be started, in which it is contained, or if it will be switched on or logged in by an action. For SMS dispatch, a modem must be switched on and logged in, but it does not have to be part of a WAN chain. DSL modems can only be switched off (e.g. for power-saving purposes) or switched on.

  • Start or stop container: The selected container will be started or stopped. The container must be active for this.

  • Start Auto-Update: The automatic update process will be started.

  • Activate firmware: The selected firmware will be activated.

  • Activate profile: The selected profile will be activated and opened.

  • Apply ASCII configuration: The selected ASCII configuration will be applied to the opened profile. If this ASCII configuration contains a Lua script, it will also be executed.

  • Start or stop countdown: The selected countdown timer will either be started or stopped.

  • Set counter: The selected counter will either be reset, incremented by one or decremented by one.

  • Set digital output: The selected digital output will be opened, closed, changed over or pulsed.

  • Set analogue output: The selected analogue output will be set to the specified value.

  • Connect or disconnect serial Ethernet gateway: The selected serial Ethernet gateway will either be connected or disconnected, i.e. the TCP connection to the specified remote terminal will be established or closed.

  • Start sleep mode: The router will be put into sleep mode. The router will restart after the expiry of the configured length, a reset, a temporary loss of power supply or change of state at one of the inputs. This functionality depends on a certain hardware equipment and is not available for all routers.

  • Certificate enrolment: renew client cert: A request for the renewal of the selected client certificate will be submitted to the certificate enrollment server.

  • Start network tool: The selected network tool call will be executed.

  • Reset device counter: The selected device counter will be reset.

Timers

Timers are used to trigger an event time-controlled. Certain timers can also be started or stopped within an action (triggered by an event). A timer will only be started, if it assigned to an action as an event.

There are three different types of timers: Fix set time, interval and countdown.

Fix set time

A timer of the type fix set time expires periodically at the specified time.
This type of timer allows to trigger periodical actions like a daily synchronisation of the clock or a daily logout/login from/to the cellular network for example.

Examples:
Fix set time: 23:05, Repetition: daily - this timer triggers an event daily at 23:05 (11:05 pm)
Fix set time: 23:05, Repetition: hourly - this timer triggers an event every hour at five minutes past the full hour (00:05, 01:05, 02:05, ...)

Interval

A timer of the type interval expires periodically after the specified interval and starts over again then. It will first be started with its configuration and with each restart of the router.
This type of timer allows to trigger periodical actions like the dispatch of status messages.

Example:
Interval: 5:15 - this timer triggers an event every 315 minutes (5*60+15)

Countdown

A timer of the type countdown will be started within an action and expires after the specified interval. It can also be stopped before its expiry within an action.
If the checkbox Restart timer on new event is checked, an already running timer will be started again by an event assigned to it, i.e. it will be reset and starts over again. If the checkbox is unchecked, the timer cannot be restarted again by an event before its expiry.
If the checkbox Deactivate timer after first expiration is checked, the timer cannot be started again. The timer will be deactivated for this and cannot even be started by an event; in order to activate it again, the checkbox active of this timer must be checked again in the list of timers.
This type of timer allows to realise sophisticated applications like cascading alarm messages or a time-delayed start of actions like a firmware update.

Example:
Countdown: 0:07, Restart timer on new event: YES, Deactivate timer after first expiration: NO - this timer triggers an event after 7 minutes, will be restarted with each occurrence of an event assigned to it, and can be restarted by an event even after its expiry.

Inserting in messages and HTTP requests

The expression for the variable is replaced with the return of a CLI command or a REST request. While the CLI expression can be used to insert the returns of all CLI commands into the text, the REST request can only be used to insert the returns of status endpoints. The following restrictions apply to the respective message types:

CLI command

REST request

SMS message text

check green

minus

E-mail subject

check green

minus

E-mail message text

check green

check green

HTTP request end point

check green

minus

HTTP request body

check green

check green

Example for a message text that outputs the current system time of the router in a message:
The current system time is $cli(status.sysdetail.system.date).

Example for a message text that uses event-dependent information in a message to output user, time and location of a login:
The user $cli(events.info[username]) logged in at $cli(administration.time.time) on location $cli(administration.hostnames.location).
For this, the message must be triggered by an event Authentication attempt has been registered - succeeded within an action.

Example for a message text that uses nested event-dependent information in a message to output the event that occurred:
The event $cli(events.event_config.event[$cli(events.info[event_id])].description) has occurred.
Here, the ID of the requested event will be inserted in the request of the event description using the event-dependent information $cli(events.info[event_id]).

If the expression $rest(/status/sysdetail/system) is inserted in a message text for example, the following return will be inserted at the position of the expression:

{
 "status": {
  "unique": {
   "location": "Regensburg",
   "date": "2025-02-27 11:32:30",
   "uptime": "21 min 1 s",
   "load": "3.30 2.95 1.96",
   "ram": "30964 kByte free",
   "hash": "2C637FC2",
   "mac": "00:05:B6:06:82:61",
   "remote_management": "inactive",
   "remote_management_uptime": "",
   "time_status": "manually_set",
   "signature_required": "inactive",
   "device_virgin": "0",
   "profile_mode": "permanent",
   "flash_mode": "SLC",
   "flash_status": "OK",
   "hostname": "insys",
   "classic_ui_active": "1",
   "device_note": "",
   "minimum_fw_version": "6.9",
   "boots_since_production": "2406",
   "boots_since_reset": "1",
   "operating_hours": "735h:45m",
   "online_count_since_production": "1056",
   "online_count_since_reset": "0",
   "online_count_since_boot": "0",
   "last_online_time": "never"
  }
 }
}

Inserting in paths

Example for using the serial number of the router to generate a device-specific path on the Auto Update server:

/updates/$cli(status.device_info.slot[1].serial_number)/list.txt

In this case, the resulting path would be: /updates/12345678/list.txt (assumed the serial number is 12345678)