This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

C

New Features

Agent One-click Update

The architecture of the maiLink Agent software has changed to support one-click updates. Updates are triggered by a user selecting the desired version of Agent software to run on the Device and then initiating the update.

Note: To perform a single-click Agent Upgrade or Downgrade, you must already have V22.9.11 (or later) installed.

Agent Upgrade

The process is simple:

  1. Navigate to Devices > DeviceID.
  2. Select Update Device from the left hand tab bar.
  3. In the Update Agent section, click the Versions pull-down and select one of the more recent versions.
  4. Click Apply to downgrade the Device to the selected version.
  5. The Current Version display will change automatically.
    • Update will take 5 to 30 seconds, depending on network speeds.

Agent Downgrade

Note: You cannot use this method to downgrade an Agent to a version earlier than V22.9.11.

The same controls are used to revert to earlier versions of the Agent.

  1. Navigate to Devices > DeviceID.
  2. Select Update Device from the left hand tab bar.
  3. In the Update Agent section, click the Versions pull-down and select one of the earlier versions.
  4. Click Apply to downgrade the Device to the selected version.
  5. The Current Version display will change automatically.
    • Update take 5 to 30 seconds, depending on network speeds.

Telemetry Metrics Display

…
By Julian Marshall |

Telemetry “metric” data can now be displayed in the Cloud. There is a section called Metrics Explorer on each Devices > DeviceID > About Device page where you can enter queries. To help you get started, a new documentation page has been added that will help you get started with queries:

Telemetry Stub-outs

2022-08-04 Update: Telemetry “metric” messages are now transmitted to the Cloud

2022-09-13 Update: Configuration of agent log files has changed. See v22.9.8

2022-11-14 Update: All telemetry messages (Metrics, Events and Status) now get transmitted to the Cloud. In addition, system metrics and status values are also sent to the cloud (must be enabled by configuration).

Two new telemetry types are supported in the Agent REST API. Messages with type “event” and “status” can now be accepted. The results of calls to the REST API are documented in the Agent logfile:

C:\Program Files\maiLink\agent\mailink-agent-plugin.log

In order to log these telemetry calls, set log.level to “trace”:

# C:\Program Files\maiLink\Agent\mailink-agent-plugin.yml
log.level: "trace"
log.file: C:\Program Files\maiLink\agent\mailink-agent-plugin.log

After changing the log level, restart the maiLink Agent service.

Workflows

Workflows are ready for use! Make sure you have Agent v23.3.6 or later installed.

Basic Overview

  1. Upgrade your devices to Agent v23.3.6 or later.
  2. Select Workflows on the maiLink UI top bar.
  3. Click Create and use the Workflow Step Builder to create your workflow.
    • Define the Trigger Type, plus a Trigger Condition if required.
    • Define the workflow steps in the right order.
    • Save the workflow.
  4. Enable the workflow by hovering over the row for your workflow and clicking the play button (⏵) at the righthand side.

Note: Be careful when select the trigger Type.
Note: Construct the Condition carefully to avoid getting thousands of unwanted triggers.

Release Notes

v23.3.7 Release Notes

Critical Release

maiData is scheduled to upgrade services in the maiLink Cloud on the weekend of April 1-2, 2023. One of those changes requires all Agents and Clients to communicate differently with the maiLink Cloud thereafter, necessitating a change in the Agent and Client software versions. See below for details.

Agent/Cloud Compatability

maiLink Agent software v23.3.7 changes the way that the Agent communicates with the maiLink Cloud. The release is necessary because maiData is scheduled to upgrade services in the maiLink Cloud on the weekend of April 1-2, 2023.

Note: All customers should upgrade the maiLink Agent on all devices to V23.3.7 by March 31, 2023.

maiLink Client software v23.3.0 changes the way that the Client communicates with the maiLink Cloud. The release is necessary because maiData is scheduled to upgrade services in the maiLink Cloud on the weekend of April 1-2, 2023.

Note: All customers should upgrade the maiLink Client on all computers to V23.3.0 by March 31, 2023.

v23.3.6 Release Notes

This version of the maiLink Agent software includes support for maiLink Workflows. In particular, this Agent will support the “Run a Command” workflow step, which allows the user to specify a single shell command that will be executed by bash (on Linux or MacOS) or PowerShell (on Windows).

Logging Changes

Logging has been improved so that, by default, there is a single Agent logfile that contains logging information for both the maiLink agent and the maiLink agent plugin.

O/S Combined Logfile
Linux /var/log/mailink/mailink-agent.log
macOS /var/log/mailink/mailink-agent.log
Windows C:\Program Files\maiLink\agent\mailink-agent.log

In addition, the content of the logfiles has been made easier to read.

System Metrics Changes

  1. Beginning with this version of the maiLink Agent, some system metrics and status values will be sent to the cloud by default.
    • md_cpu_used_percent
    • md_memory_used_percent
  2. All system status values except for disk partition information will be sent to the cloud by default.
  3. Network interface data has been parsed so that IPV4 and IPV6 information is shown separately.

v23.1.2 Release Notes

Bug Fix

This version of the maiLink Agent software fixes a problem for certain versions of Windows that prevented the Agent from starting correctly.

Note: It is possible that on some versions of Windows you may not get some of the default CPU telemetry messages. That is being investigated further.

Older Release Notes

Archived Release Notes (2022)

v22.12.4 Release Notes

File Pull from Device

The maiLink Agent software has been updated to incorporate the ability to transfer a file to the cloud upon a request from the cloud. That lets the user “pull” a file from the maiLink cloud portal. In order to use this feature, the user must specify the absolute path of the file that is to be pulled to the cloud.

File Transfer

All file transfer functions have been reimagined under the Devices > {device} > File Transfers lefthand tab. You will now see two top tabs under the File Transfers heading: Send to Device, and Pull from Device.

The user interface now has an Uploaded Files table that shows a list of the files that have been either pulled from the device to the cloud, or pushed by the device to the cloud (via the Agent REST API).

Send to Device. This functionality has not change from prior releases, although the user interface has changed. The user selects a file on their local file system, which is then transferred to the cloud. Then it is transferred down to the device.

Pull from Device. The user “pulls” a file from the maiLink cloud portal. The user must specify the absolute path of the file that is to be pulled to the cloud.

Device Location and Maps

Location. Each device can now be associated with a street address. That address is used to derive a latitude and longitude for the location. Furthermore, you can embellish the address with building, floor, and suite reference information, but realize that the additional information may not influence the latitue and longitude. The following examples will all create the same latitude and longitude:

  • 1111 Constitution Avenue Northwest, Washington, District of Columbia, DC
  • 1111 Constitution Avenue Northwest, Washington, District of Columbia, DC, Building 13
  • 1111 Constitution Avenue Northwest, Washington, District of Columbia, DC, Suite 103
  • 1111 Constitution Avenue Northwest, Washington, District of Columbia, DC, Bldg 7, Suite 24

There are several ways to enter the address:

  • For a new device, add the address in the device entry area.
  • For an existing device, add the address by editing the device.
  • When mass importing devices from a CSV file, you can incorporate the address into the CSV file (see below, and How to Import Devices).

Mass Import of Devices

maiLink now support mass import of devices through our technical support team. Our documentation pages contain information (see How to Import Devices) on how to create a CSV file that is compatible with our mass import capability. If you have any questions, please reach out to support@maidata.io.

v22.11.6 Release Notes

Telemetry Events

The maiLink Agent software has been updated to transmit telemetry event data to the cloud. As in prior maiLink Agent releases, the telemetry event data can still be logged to a file on the device by setting the log.level in mailink-agent-plugin.yml to trace.

Telemetry Status

The maiLink Agent software has been updated to transmit telemetry status data to the cloud. As in prior maiLink Agent releases, the telemetry status data can still be logged to a file on the device by setting the log.level in mailink-agent-plugin.yml to trace.

Built-In System Telemetry

Prior releases of maiLink Agent included built-in system telemetry that transmitted CPU and memory utilization data to the cloud. This has now been greatly extended to include the following:

System Type Unit Property
os status text Operating system type.
system_boot_time status Seconds Most recent system boot time (since epoch).
system_up_time status Seconds Time elapsed since completion of the last system boot.
CPU Type Unit Property
cpu_cpus status number Number of physical CPUs available.
cpu_cores status number Number of CPU cores available.
cpu_frequency status MHz CPU clock frequency.
cpu_model_name status text CPU model name.
cpu_used_percent metric % Fraction of CPU in use.
cpu_vendor_id status text CPU vendor name.
Memory Type Unit Property
memory_free_bytes metric Bytes Free memory.
memory_total_bytes status Bytes Amount of available memory.
memory_used_bytes metric Bytes Used memory.
memory_used_percent metric % Fraction of memory in use.
Network Type Unit Property
interface_ip_addresses status text IP Address of this network interface.
interface_mac_address status text MAC Address of this network interface.
interface_name status text Name of this network interface.
Disk Type Unit Property
partition_device status text Name of disk drive for this partition.
partition_free_bytes metric Bytes Free disk partition space.
partition_fstype status text Name of partition file system type.
partition_mountpoint status text Name of disk drive mount point for this partition.
partition_total_bytes status Bytes Amount of disk space available in this partition.
partition_used_bytes metric Bytes Used disk partition space.
partition_used_percent metric % Fraction of disk partition space in use.

Control. By default, your device does not transmit all of the above information to the cloud. However, starting in this release you can enable any of the above items for automated transmission. To enable the items, edit mailink-agent-plugin.yml and add any or all of the following data items below. Note that you can easily disable any of them at any time by setting enabled:false.

Note: In a future release, controls over the enabling/disabling of built-in system telemetry will be moved to the Device Type controls in the cloud.

telemetry:
  metric:
    partition:
      free_bytes:
        enabled: true
      used_bytes:
        enabled: true
      used_percent:
        enabled: true
    memory:
      used_bytes:
        enabled: true
      used_percent:
        enabled: true
      free_bytes:
        enabled: true
    cpu:
      used_percent:
        enabled: true
  status:
    os:
      enabled: true
    system:
      boot_time:
        enabled: true
      up_time:
        enabled: true
    cpu:
      cpus:
        enabled: true
      cores:
        enabled: true
      vendor_id:
        enabled: true
      model_name:
        enabled: true
      frequency:
        enabled: true
    partition:
      device:
        enabled: true
      mountpoint:
        enabled: true
      fstype:
        enabled: true
      total_bytes:
        enabled: true
    memory:
      total_bytes:
        enabled: true
    interface:
      name:
        enabled: true
      mac_address:
        enabled: true
      ip_addresses:
        enabled: true

The maiLink web port has been updated to reflect the telemetry changes described above.

Display of Telemetry Status Data

Telemetry status information is now displayed in the user interface at Devices > [Device] > About [Device] > System Status. The data displayed here includes both any enabled built-in system telemetry status data as well as all the custom telemetry status data that your system is transmitting to the cloud.

Note: The data displayed is the most recent status value received for each of the status parameters.

Display of Telemetry Events Data

Telemetry events are now displayed as a graphical overlay in the metrics explorer as vertical dashed lines.

Note: Individual events cannot be enabled or disabled at this time.

Display of Built-In System Telemetry Metric Data

Built-in system telemetry data that is sent as metrics (dynamic numeric data) can be selected for graphical display by clicking on the Add Query button in the metrics explorer found at Devices > [Device] > About [Device] > Metrics Explorer.

v22.10.7 Release Notes

File Push REST API

The maiLink Agent software REST API has been extended to include a new endpoint that allows the Agent to push a file to the Cloud. This can be performed programatically by the Device’s applications software, or can be performed from the command line with a simple Curl instruction.

Files transferred can be of any size. The Agent divides very large files in the sections to better ensure completion of file transfers in the event of connectivity interrupts; transfer will continue if connection is re-established after a connectivity interruption.

The REST API is documented at link.

The JSON message passed to the REST API at localhost:5465 contains the complete path for the file to be uploaded and the destination path in the cloud relative to the storage bucket:

{
    "path": "/Users/maidata/files/upload_this.txt",
    "destinationPath": "configs/config.txt"
}

Users can access the uploaded files through a table in the maiLink web portal at

Devices > [Device] > File Transfers > Uploaded Files

v22.9.11 Release Notes

One-Click Agent Update

The maiLink Agent software architechture has changed so that it supports Agent self-update. To do this, the Agent has been divided into two parts: mailink-agent is a watchdog that runs continuously as a daemon or service; mailink-agent-plugin is a binary that runs at the behest of mailink-agent. When an update is performed, mailink-agent-plugin gets replaced.

Should an update fail, the Agent will revert to using the version of mailink-agent-plugin that was running just prior to initiation of the update.

Configuration File

The maiLink Agent plugin has a new configuration file, written in YAML. That is where you can configure the behavior of the Agent, most specifically for logging.

Windows. On Windows devices the configuration file is found at:

C:\Program Files\maiLink\agent\mailink-agent-plugin.yml

with the following default contents:

log.level: "info" # or debug / trace
log.file: C:\Program Files\maiLink\agent\mailink-agent-plugin.log

Linux. On Linux devices the configuration file is found at:

/etc/mailink/mailink-agent-plugin.yml

with the following default contents:

log.level: "info" # or debug / trace
log.file: /var/log/mailink/mailink-agent-plugin.log

Logging

The Agent plugin logs run-time information about the Agent plugin. For users, this is most useful for monitoring REST API activity for Telemetry stub-outs. The Agent plugin will only log telemetry messages received by the REST API if the log level is set to “trace” in the YAML configuration file.

This release fixes a bug that prevented mailink-agent from creating its log file.

v22.9.8 Release Notes

One-Click Agent Update

This release is identical to v22.9.9 except for the version number. It is provided to allow testing of one-click Agent update so you have to working versions you can switch between. v22.9.8 and v22.9.9 are functionally equivalent.

For details on new functionality and changes introduced in v22.9.8/v22.9.9, see Release Notes

v22.8.4 Release Notes

Telemetry: Metrics

The REST API in the maiLink Agent now transmits “metric” type Telemetry messages to the Cloud. Those messages are recorded in the maiLink Telemetry Cloud database. Each metric is a named value where the name connotes the concept with unit (when applicable) and the value is a numeric value.

For example:

    {
        "type": "metric",
        "label": "pressure__mmHg",
        "value": 13.3
    },

Telemetry Time-Series Display

With this release you can display telemetry time-series plots. A new Dashboard block called “Metrics Explorer” is available on each Device page. To support this, several new pages of Metrics documentation have been added (see below).

Note that in a future release we plan to move this capability to the Device Type. It will be available in the Device page only for users with the correct permissions.

Built-in System Metrics

The maiLink Agent has been updated to automatically include host computer and operating system metrics as Telemetry “event” data sent to the Cloud. Two metrics have been created:

cpu_util        # CPU % used
mem_util        # Memory % used

Built-in System Metrics are available via queries in the Metrics Explorer.

File Transfer

maiLink now supports file transfer from the service specialist’s computer to an Agent in the field. The user selects a file on the local computer to transmit. The file is deposited into this directory:

C:\Program Files\maiLink\agent\file_transfers\

The source file is not removed.

Audit Logging

maiLink now has a comprehensive Audit Log trail that you can review. Find under Settings > Audit Logs.

Documentation

Documentation is available at Docs or by clicking on the Support tab in the top bar in the Cloud.

Release Notes

A section that contains release notes has been added. In this area you can find information about the most recent release of maiLink SRM software modules. In the future you will also be able to find historical release notes about prior software versions.

Telemetry API Specification

The Telemetry API interface specification has been updated to reflect the final syntax for Event and Status telemetry messages.

Metrics Documentation

Several new pages of documentation to help users learn about the PromQL query language used in the Metrics Explorer on the Device page. The pages are (in the order of most basic to most complex):

In addition, a new page has been added with coding samples that will generate telemetry Metrics data for you to play with:

v22.7.7 Release Notes

Telemetry Stub-out

Two new telemetry types are supported in the Agent REST API. Messages with type “events” and “status” will now be accepted. The results of calls to the REST API are documented in the Agent logfile:

C:\Program Files\maiLink\agent\mailink-agent.log

In order to log the telemetry calls, set MAILINK_LOG_LEVEL to “trace”:

C:\Program Files\maiLink\Agent\mailink-agent.cfg

  MAILINK_DEVICE_KEY_FILE=C:\Program Files\maiLink\agent\agent.jwt
  MAILINK_LOG_LEVEL=trace
  MAILINK_LOG_FILE=C:\Program Files\maiLink\agent\mailink-agent.log

After changing the log level, restart the maiLink Agent service.

v22.7.1 Release Notes

Client Connection Indicator

The user interface reflects whether the device is connected by showing a green dot in the menu bar at the top of the app.maidata.io user interface.