set alarm

Purpose

Configures device alarms and display current alarm settings. Device alarms are used to send emails or SNMP traps when certain device events occur. These events include

For Digi devices managed by a remote manager, the cwm option sends all alarms to a Remote Manager server.

The number of alarms that can be configured varies by product. To determine the number of alarms, enter set alarm ? and view the range specified for the range parameter. For example, this range parameter indicates that up to 8 alarms can be configured:

range=1-8

To avoid false errors, configure alarms while alarms are disabled, by entering a set alarm state=off command, then enable alarms after they are fully configured by entering set alarm state=on.

Required permissions

For Digi products with two or more users, set permissions to set permissions s-alarm=read to display current alarm settings, and to set permissions s-alarm=rw to display alarm settings and configure alarms. See set permissions for details on setting user permissions for commands.

Syntax

Configure alarms with general options—these settings apply to all alarms

set alarm [state={on|off}]
  [mailserverip=ipaddress]
  [from=string]
  [dcloud={on|off}]

Configure alarms for a range—set multiple alarms

set alarm range=range 
  [active={on|off}]
  [type={email|snmptrap|sms|email_snmp|email_sms|snmp_sms|all}]
  [to=string]
  [cc=string]
  [subject=string]
  [priority={normal|high}]
  [sms_to=address] 
  [sms_cc=address]
  [mode={match|gpio|rssi_gsm|rssi_1xrtt|rssi_1xevdo|ecio_1xrtt|
    ecio_1xevdo|cell_data|mobile_temp|1xevdo_unavail|
    mobile_unavail|mobile_cfg_chng}]

Configure alarms based on GPIO pin states, where n is the GPO pin number

set alarm range={1-32} mode=gpio
  [pins=list of pins]
  [highpins=list_of highpins]
  [lowpins=list of lowpins]
 [pin{n}={{high|1}|{low|0}}{ignore|x}}]
  [trigger_interval=seconds]
  [reminder={on|off}]
  [reminder_interval=seconds]

Configure alarms based on data pattern matching

set alarm mode=match
  match=string
 port=port_range

Note The port=port_range option is present only if there is more than one port on the device. port_range is replaced by the number of serial ports.

Configure alarms based on mobile signal strength—GSM

set alarm mode=rssi_gsm
  sig_strength_threshold=threshold
 time=time
 optimal_alarms_enabled={on|off}

Configure alarms based on signal strength—CDMA

set alarm mode={rssi_1xrtt|rssi_1xevdo|ecio_1xrtt|ecio_1xevdo}
  sig_strength_threshold=threshold
 time=time 
  optimal_alarms_enabled={on|off}

Configure alarms based on 1xevdo service unavailable

set alarm mode=1xevdo_unavail
  time=time
 optimal_alarms_enabled={on|off}

Configure alarms based on mobile service unavailable

set alarm mode=mobile_unavail
  time=time
 optimal_alarms_enabled={on|off}

Configure alarms based on mobile configuration changes

set alarm mode=mobile_cfg_chng

Configure alarms based on mobile temperature changes

set alarm mode=mobile_temp
  temperature=temperature 
 optimal_alarms_enabled={on|off}

Set alarms based on cellular data traffic

set alarm mode=cell_data 
  cell_data=byte count threshold
 cell_data_type={receive|transmit|total}
  time=max time

Display current alarm settings

set alarm [range={1-8}]

Options

General alarm options

state= {on|off}

Enables or disables all alarms.

on

Enables all alarms.

off

Disables all alarms.

To avoid false errors, it is recommended that you configure alarms while alarms are disabled, and enable alarms after they are fully configured.

The default is off.

mailserverip=ipaddress

Used to configure IP address of the mail server to which alarm-triggered emails are sent.

from=string

The text to be included in the from field of an alarm-triggered email.

dcloud={on|off}

This option is displayed but not supported. For Remote Manager alarm functionality, see the alarms section of the Digi Remote Manager User Guide.

Options for setting multiple alarms with the “range” option

range=range

The alarm or range of alarms for which alarm options are set. The number of alarms that can be configured varies by product. To determine the number of alarms, enter set alarm ? and view the range specified for the range parameter. For example, range=(1 - 8) indicates that up to 8 alarms can be configured.

active={on|off}

Enables or disables an alarm.

on

Enables an alarm.

off

Enables an alarm.

The default is off.

type={email|snmptrap|sms|email_snmp|email_sms|snmp_sms|all}

Used to determine what kind of an alarm is sent.

For SNMP traps to be sent, the IP address of the system to which traps are sent must be configured, by issuing a set snmp command with the trapdestip option. See "set snmp" on page 379.

email

Alarm is sent as an email.

snmptrap

Alarm is sent as an SNMP trap. If specified, the subject text is sent with the alarm. The MIBs for these traps are DIGI‑SERIAL‑ALARM‑TRAPS.mib, and DIGI-MOBILETRAPS.mib.

sms

Alarm is sent as SMS text.

email_snmp

Alarm is sent as email and SNMP trap.

email_sms

Alarm is sent as email and SMS text.

snmp_sms

Alarm is sent as an SNMP trap and SMS text.

all

Alarm is sent as email, SNMP trap, and SMS text.

The default is email.

Note on sending alarms as SMS text: For SMS alarms, such alarms are suitable only for cellular products that support SMS, and only if SMS is included in the mobile service account for the cellular modem. There may be additional charges for SMS service or individual short messages, according to the customer's service agreement.

to=string

The text to be included in the to field of an alarm-triggered email.

cc=string

The text to be included in the cc field of an alarm triggered email.

subject=string

If type=email, this option specifies the text to be included in the subject field of an alarm-triggered email. If type=snmptrap, this option specifies the text to be included in the Serial Alarm Subject field of an alarm‑triggered SNMP trap.

priority={normal|high}

The priority of the triggered email.

normal

The email is sent with normal priority.

high

The email is sent with high priority.

The default is normal.

sms_to=address

The address of the recipient to receive the SMS text. This option’s value is typically specified as a destination phone number or a short code appropriate to SMS.

sms_cc=address

The address of recipient to receive a copy of the SMS text. This option’s value is typically specified as a destination phone number or a short code appropriate to SMS.

mode={match|gpio|rssi_gsm|rssi_1xrtt|rssi_1xevdo|ecio_1xrtt|ecio_1xevdo|cell_data|mobile_temp|
1xevdo_unavail|mobile_unavail|mobile_cfg_chng}

The alarm mode, which determines what type of event will trigger an alarm.

The default mode is gpio, unless the Digi product does not support GPIO pins, in which case, the default is match.

match

An alarm will be triggered when a pattern is found in the stream of serial data on the specified port.

gpio

Transitions for GPIO pins will trigger alarms. See "GPIO pin state-based alarm options" on page 174 for more information.

rssi_gsm

Triggers alarms when the average signal strength on a GSM device falls below a specified threshold for a specified amount of time. Optionally, a subsequent alarm is triggered when signal strength returns to the optimal state above the threshold.

rssi_1xrtt

Triggers alarms when the average RSSI 1xRTT signal strength on a CDMA device falls below a specified threshold for a specified amount of time. Optionally, a subsequent alarm is triggered when signal strength returns to the optimal state above the threshold.

rssi_1xevdo

Triggers alarms when the average RSSI 1xEVDO signal strength on a CDMA device falls below a specified threshold for a specified amount of time. Optionally, a subsequent alarm is triggered when signal strength returns to the optimal state above the threshold.

ecio_1xrtt

Triggers alarms when the average Ec/Io 1xRTT signal strength on a CDMA device falls below a specified threshold for a specified amount of time. Optionally, a subsequent alarm is triggered when signal strength returns to the optimal state above the threshold.

ecio_1xevdo

Triggers alarms when the average Ec/Io 1xEVDO signal strength on a CDMA device falls below a specified threshold for a specified amount of time. Optionally, a subsequent alarm is triggered when signal strength returns to the optimal state above the threshold.

cell_data

Triggers alarms based on cellular data exchanged in an amount of time.

mobile_temp

Triggers alarms when the mobile temperature goes above a specified threshold. Optionally, a subsequent alarm is triggered when signal strength returns to a temperature below the threshold.

1xevdo_unavail

Triggers alarms when 1xEVDO service is unavailable for a specified amount of time. Optionally, a subsequent alarm is triggered when service becomes available again.

mobile_unavail

Triggers alarms when mobile service is unavailable (not registered on the home network) for a specified amount of time. Optionally, a subsequent alarm is triggered when service becomes available again.

mobile_cfg_chng

Triggers alarms when the mobile configuration is changed.

GPIO pin state-based alarm options

In GPIO mode, alarms are triggered when there are transitions between states for GPIO pins. These options allow you set which GPIO pins’ transitions trigger alarms. Setting alarms in GPIO mode is supported in some but not all Digi devices.

pins=list of pins

A list of GPIO pins that trigger alarms.

highpins=list of highpins

A list of GPIO pins that trigger alarms when a pin’s signal is high.

lowpins=list of lowpins

A list of GPIO pins that trigger alarms when a pin’s signal is low.

pin{n}={{high|1}|{low|0}|{ignore|x}}

An alternative way to specify the action of a given GPIO pin, where n is the pin number.

high or 1

The pin will trigger an alarm when the pin’s signal is high.

low or 0

The pin will trigger an alarm when the pin’s signal is low.

Ignore or x

The pin will not trigger an alarm.

The default is ignore.

reminder={on|off}

The type of reminder sent.

on

An email or SNMP trap is sent periodically while the alarm-triggering event is active. The interval is based on the value of the reminder_interval option.

off

An email or SNMP trap is sent only when an alarm is triggered.

reminder_interval=seconds

The minimum reminder interval in seconds. Indicates how often an email or SNMP trap is sent when the reminder option is set to on and an alarm-triggering event is active.

trigger_interval=seconds

The minimum trigger interval in seconds. If the reminder option is set to off, this option indicates the minimum amount of time that is allowed between alarm-triggered emails or SNMP traps.

Data pattern matching-based alarm options

In data pattern match mode, an alarm will be triggered when a pattern is found in the stream of serial data. These options are used for setting alarms in data pattern match mode:

mode=match

Sets the alarm to match mode.

match=string

A string that triggers an alarm if the data pattern is found in the incoming serial stream. The maximum length of this string is 40 characters, including escape sequences for special characters. For more details on the escape sequences, see "Entering Special Characters in String Values" on page 11. The maximum parsed length of this string is 10 characters. That is, this string must reduce down to a 10-character string when the escape sequences are processed.

port=port_range

Specifies the port or range of ports that will be monitored for the specified match string.

Signal-strength-based alarm options

Options for setting alarms based on signal strength are supported in cellular-enabled products only. Note that not all signal-strength options are available with all radios. To determine which signals can be monitored, use the “display mobile” command. If a signal is displayed, it can be monitored.

mode=rssi_gsm

Sets the alarm to signal-strength mode for a GSM radio.

mode=rssi_1xrtt

Sets the alarm to 1xRTT RSSI signal-strength mode for a CDMA radio.

mode=rssi_1xevdo

Sets the alarm to 1xEV-DO RSSI signal-strength mode for a CDMA radio.

mode=ecio_1xrtt

Sets the alarm to 1xRTT Ec/Io signal-strength mode for a CDMA radio.

mode=ecio_1xevdo

Sets the alarm to 1xEV-DO Ec/Io signal-strength mode for a CDMA radio.

signal_strength_threshold=threshold

The threshold average signal strength., This is measured in dBm for rssi_gsm, rssi_1xrtt, and rssi_1xevdo—typically -120 dBm to -40 dBm—and dB for ecio_1xrtt and ecio_1xevdo—typically -24 dB to -2 dB.

Note that a value of 0 dB reported by a display mobile command when there is no signal strength should properly be interpreted as the minimum value, which is -120 dBm or -24 dB.

time=time

The time in minutes that the average signal strength stays below the threshold specified on the signal_strength_threshold option.

optimal_alarms_enabled={on|off}

If optimal alarms are enabled, an optimal alarm will also be sent when the signal strength returns to a value that is above the specified threshold. Default is off.

Cellular data traffic-based alarm options

These options for setting alarms based on cellular data traffic are supported in Digi Cellular Family products only.

mode=cell_data

Sets the alarm to cellular-data mode.

cell_data=byte count threshold

The number of bytes of cellular data to be counted before triggering an alarm.

cell_data_type={receive|transmit|total}

The type of cellular data to be counted.

receive

Data received by the Digi device.

transmit

Data transmitted by the Digi device.

total

The total data received and transmitted the Digi device.

time=max time

The time, in minutes, during which bytes of cellular data are counted.

Mobile temperature-based alarm options

These options for setting alarms based on the radio’s reported temperature are supported in Digi Cellular Family products only. Note that temperature-based options are not available with all radios. To determine if your radio supports these alarms, use the display mobile command. If the temperature is displayed, it can be monitored.

mode=mobile_temp

Sets the alarm to mobile temperature mode.

temperature=temperature

The temperature threshold in degrees Celsius.

optimal_alarms_enabled={on|off}

If optimal alarms are enabled, an optimal alarm will also be sent when the temperature returns to a value that is below the specified threshold. Default is off.

Mobile service-based alarm options

These options for setting alarms based on the service state of the radio are supported in Digi Cellular Family products only. Note that some service-based options are not available with all radios. To determine if your radio supports these alarms, use the display mobile command. If the service is displayed, it can be monitored.

mode=1xevdo_unavail

Sets the alarm to monitor 1xEV-DO service.

mode=mobile_unavail

Sets the alarm to monitor registration status. Any registration status other than Registered (Home Network) is considered to be a mobile unavailable status.

time=time

The time in minutes that the specified service has been unavailable.

optimal_alarms_enabled={on|off}

If optimal alarms are enabled, an optimal alarm will also be sent when the service being monitored is reestablished. Default is off.

Mobile configuration change alarm options

This option for setting alarms based on a change to any of the mobile-oriented configurations is supported in the cellular-enabled products only. The following configuration items are monitored: PPP settings associated with the mobile radio (set mobileppp and set ppp); PPP Bridge settings (set passthrough); Mobile settings (set surelink); or mobile provisioning, manual or IOTA.

mode=mobile_cfg_chng

Sets the alarm to monitor mobile configuration changes.

Examples

Set a GPIO alarm and send an email message or SNMP trap

This example shows how to set up a GPIO alarm to trigger when two GPIO pins go high, and sending an email message when they do. It also shows how to change from sending an email message when the alarm condition occurs to issuing an SNMP trap.

  1. Turn off alarms and set global email properties (this is done to avoid false error conditions triggering alarms):
#> set alarm state=off mailserverip=10.0.0.1 from=myemail@digi.com
  1. Set alarm 1 mode to GPIO mode:
#> set alarm range=1 mode=gpio
  1. Set alarm 1 to designate which pins trigger alarm:
#> set alarm range=1 pin2=high pin3=1
#> set alarm range=1 highpins=2,3
  1. Set alarm 1 to send an email message when the alarm condition is met, and enable alarm 1:
#> set alarm range=1 active=on type=email to=destination@digi.com subject=”Alarm 1 triggered”
  1. Change alarm 1 to send an SNMP trap:
#> set alarm range=1 highpins=2,3 type=snmptrap
  1. Enable alarms:
#> set alarm state=on

Set up signal-strength and cellular-traffic alarms and send them to Remote Manager

This example shows how to set up two alarm and have them sent to Remote Manager. It configures two alarms:
Alarm 1 for is based on a threshold signal strength value (rssi), and
Alarm 2 is based on cellular data traffic (cell_data).

  1. Disable alarms during configuration:
#> set alarm state=off
  1. Set alarm 1 to trigger when average GSM rssi drops below -80 dB for at least 20 minutes. Turn alarm 1 on.
#> set alarm range=1 active=on mode=rssi_gsm sig_strength_threshold=-80 time=20
  1. Set alarm 2 to trigger when more than 10000 bytes are sent in a period of 5 minutes. Turn alarm 2 on.
#> set alarm range=2 active=on mode=cell_data cell_data=10000 cell_data_type=transmit time=5
  1. Set alarm 3 to trigger when mobile radio temperature exceeds the default thresholds. Turn alarm 3 on.
#> set alarm range=3 active=on mode=mobile_temp
  1. Set alarm 4 to trigger when 1xEV-DO service is unavailable for a period of 3 minutes and also trigger when service becomes available again. Turn alarm 4 on.
#> set alarm range=4 active=on mode=1xevdo_unavail time=3 optimal_alarms_enabled=yes
  1. Set alarm 5 to trigger when the mobile configuration has been changed. Turn alarm 5 on.
#> set alarm range=5 active=on mode=mobile_config_change
  1. Set all alarms to be sent to Remote Manager, and turn on alarms: 
#> set alarm state=on dcloud=on

See also