glp/0/{SID}/(rq|fb)/cfg

This topic accepts and reports the segment's configuration, used to control properties that govern the overall behavior of the segment. This topic is refreshed whenever the edge server starts, because its content can be affected by configuration files or other parameters to the edge server. Any other change to the segment configuration object also refreshes the object in the feedback channel.

Clients can publish a complete or partial configuration object in the request channel or publish an update action with a complete or partial configuration object. Other inputs, such as input derived from edge protocol or system events, may also change the configuration object and trigger the publication of the new object in the feedback channel.

Properties

The segment configuration object has the following properties:

Field Name

Type

Notes

black

List of strings

List of blacklisted devices using the device’s protocol identifier and its protocol-specific unique identifier.
Blacklisted devices are ignored by automatic discovery procedures. The list can be empty or null.

For example: [ "lon:050320CAB2105" ]

time

Object

time is used to configure the current UTC time and date and the local timezone and daylight savings rule.

Date and time values embedded within the time object are broken into numeric components. These values reported in the feedback channel are as they were last assigned, and do not necessarily reflect the edge server's current date and time.

These are always in UTC, the edge server computes local time based on UTC time and the timezone rules included with the time object.

The time object has these fields:

Field Name	Type	Description
day	number	The number of the day in the month (1..31)
hour	number	The hour uses the 24-hour clock (0..23)
minute	number	Minutes (0..59)
month	number	Month (1..12)
second	number	Seconds (0..59) Due to unavoidable and unknown latencies between publication of the new time configuration on the CMS and processing on the edge server, the seconds might be incorrect by the time this information is processed by the edge server.
tz	string	Time zone. Timezone and daylight savings rules are described using the POSIX.1 “TZ” format. See http://man7.org/linux/man-pages/man3/tzset.3.html for the format specification. Note: The zone field (described below) is preferred for systems that support it. Commonly recognized timezone names such as CET, PDT, or GMT are preferred over the angle-bracket form, used for timezone names in UTC, such as <UTC-8>, because UTC doesn't follow daylight savings.
tz	string	Example: "CET-01:00CEST,M3.5.0,M10.5.0"
wday	string	Weekday is either Mon, Tue, Wed, Thu, Fri, Sat, or Sun
year	number	The year (nnnn).
year	number	Example: 2018
zone	string	(Optional) A zone name is supported. The name should follow the IANA zoneinfo names (such as Europe/London), which can be used for display. zone should be used for any system that supports it. POSIX "TZ" is the legacy method. In either case, you will have to use non-IAP methods of updating the relevant zone info files.
Example: { /* time obj */ year: 2018, month: 8, day: 23, ... }

discovery

Number

The discovery property enables and configures automatic device discovery procedures, executing periodically and automatically. For more explicit control over device discovery see Manual Device Discovery.

discovery uses a value in the 0..1 range to indicate the relative discovery speed, where 0 means “no discovery” and 1 means “as fast as possible.”

This property is ignored if discovery is not supported, as indicated in the About topic.

The edge processor is responsible for selecting an appropriate discovery frequency, suitable for the edge protocol and its condition within this segment, if device discovery is an active process undertaken by the edge processor. The edge processor may ignore this guidance, for example for systems where device discovery is a passive process from an edge processor’s point of view.

events

List of event category names.

List of event categories for live event reporting (see Events). The possible values are:

- “debug”
- “info”
- “warning”
- “error”
- “data”
- “alarm.”

key

List of strings

(Optional) List of key values. Up to one key for each protocol may be provided a key in a protocol-specific format. IAP has no generic meaning for this attribute, but the usage shall be unambiguous within a given protocol.

For example, a LonTalk processor might use this for the authentication key shared among all devices governed by the edge server, while a Control-M processor might use this for the radio communication encryption key.

Example:
[ "lon:F012C3AFF0210" ]

language

string

The currently selected language for localized diagnostics. The default is “en” (English).

The language parameter selects one of the available languages for localized diagnostics. Available languages are reported in the edge server’s About topic.

loc

object

The location object identifies the location of the edge server. It consists of the properties described in Location Object.

log_days

Number

Number of days to keep an event log. See Events.

smtp

Internet server object

(Optional) The Internet Server object defines an email server. The following table lists the properties for smtp and ntp.

FieldName	Type	Notes
address	string	(Required) DNS name or IP address of the server. Example: "mail.acme.com"
port	number	(Optional) Port number.
protocol	string	(Optional) Protocol. The protocol can often be inferred from the context in which this Internet Server object is used. Example: "smtp"
security	string	(Optional) Select the type of security you are using: Either “starttls”, “ssl/tls”, or null for none.
user	string	(Optional) The username (used with passwd, described below).
passwd	string	(Optional) The password for the username (used with user, described above).

mode

String

(Optional) Possible values are: onnet, offnet, or maintenance.

The default is: onnet

Protocol drivers watch the feedback channel’s segment configuration object and implement the following behavior based on the value reported with this property:

mode value	Description
onnet	Enables unconstrained operation including edge protocol communication for datapoint monitoring and network maintenance.
offnet	Suspends all edge protocol operations initiated by the edge protocol driver. One-time operations such as those to provision, deprovision, test, or load a device are processed when the mode returns to onnet. Repeated operations, such as those related to datapoint value monitoring by polling, or those in relation to periodic automatic device discovery, are suspended and resumed once the mode permits these again. But those invocations missed while in offnet mode are not executed later. Protocol drivers can respond to edge protocol transactions initiated by a third party while in offnet mode to satisfy that third party, such as to acknowledge an incoming message. Each protocol driver must select the appropriate behavior in such a situation.
maintenance	Suspends all edge protocol operations in relation to datapoint value monitoring by polling or by events. In maintenance mode, protocol drivers will minimize the edge protocol bandwidth usage, and no IAP/MQ datapoint value events will be generated. All other operations are permitted in maintenance mode. This includes specifically those used to enable and diagnose edge devices, such as actions to create, provision, or load.
any other value	Protocol drivers ignore any other value of the property, but they can report a warning to state that this mode has no effect on that driver.

ntp

Internet server object

(Optional) The Internet Server object defines a Network Time Protocol (ntp) server. See smtp above for a description of the properties.

tracing

Boolean

(Optional) Enable or disable tracing. When enabled, tracing records every change to the IAP feedback and request channels within an edge server. Because of the potentially significant data volume and performance impact of processing this data, tracing is disabled by default.

Default is False.

uplinkFreq

number

(Optional) Three timers (uplink_freq, uplink_idle, and uplink_drop) govern the use of a dial-up modem through which the edge server establishes an uplink connection to the CMS’ message broker. These timers are ignored by units with permanent networking connections.

uplink_freq defines the frequency, in seconds, with which the uplink is enabled. This enables the radio. The edge server must handle failure in a way suitable for the radio technology. For example, it could try every 90 seconds to enable the radio, obtain signal, obtain an IP address, etc.

Once the uplink is available, the timer is started for the next interval. The uplink_freq defines the duration between “radio on” events, not the radio downtime duration.

Example: 14400

uplinkIdle

number

Three timers (uplink_freq, uplink_idle, and uplink_drop) govern the use of a dial-up modem through which the edge server establishes an uplink connection to the CMS’ message broker. These timers are ignored by units with permanent networking connections.

uplink_idle defines the maximum duration of the idle period in an open uplink connection, in seconds. When no networking traffic is encountered for this idle period, the radio is shut down.

The edge server specification defines what constitutes an idle link, since the ability to determine idleness may be hardware dependent. Some controllers may be able to detect “true idleness” while others may only be able to detect idleness in terms of IAP messages.

A value of 0 (zero) disables the idle timeout.

Example: 60

uplinkDrop

number

Three timers (uplink_freq, uplink_idle, and uplink_drop) govern the use of a dial-up modem through which the edge server establishes an uplink connection to the CMS’ message broker. These timers are ignored by units with permanent networking connections.

uplink_drop defines the maximum duration of an uplink connection, regardless of its idleness. A value of 0 (zero) disables the enforced expiry timeout.

Example: 300

name

String

(Optional) String containing a name for the segment. Can be missing or null.

Example: "Assembly Line 3"

desc

String

(Optional) String containing a description for the segment. Can be missing or null.

Example: "A segment to control and monitor assembly line 3.”

Segment Configuration

Properties