MACH10 Client - PRELIMINARY

The MACH10 cloud platform allows for remote management of Lantronix gateways and OEM devices using the installed MACH10 client and MACH10 serial APIs. The MACH10 client connects the gateway with the MACH10 cloud and can be easily configured using the Web Manager or via the CLI. Developers can use the MACH10 serial APIs to send and receive data on the serial line (Line 1 or virtual line).

You can use the SDK to implement a line protocol to interpret data received on the line in terms of MACH10 Serial API commands. For SDK information, contact Lantronix Sales and FAE.

To access the MACH10 Serial API over the serial Line, configure the Line operating mode to MACH10 Command Interface. The MACH10 Command Interface line mode provides a command interface to the MACH10 serial API.

The installed MACH10 client contains settings to connect the gateway with the MACH10 cloud. To use the MACH10 client, the MACH10 settings must be configured on the gateway. See MACH10 Device Configuration and MACH10 Line and Virtual Line Configuration.

MACH10 Serial API

The following commands are accessible through the MACH10 Serial API.

Command Description Gateway Action
mach10_getsettings This command sends a request to the Lantronix gateway to read the device's configuration settings. The gateway reads the configuration for the serial device.
mach10_register<payload> This command registers the device with the MACH10 server. You need to register the device and obtain the device authentication token before you can execute other device API calls. The gateway sends the request to register the device through the REST APIs. The gateway receives the response and parses and keeps a copy of the auth_token for subsequent commands.
mach10_status<auth_token>,<payload> This command sends the current device status to MACH10. Use this command to send device attributes for the capabilities that the device supports. Send the status update using the REST API.
mach10_update<auth_token>,<payload> This command sends a request to check for all available firmware or configuration updates for the device. The response returns details about the available update. Send the request to check for an update through the REST API.
mach10_download<auth_token>,<payload> Send a request to download the content file to the device. The request parameter includes the file info returned from MACH10 in the mach10_update command. Send the request to download the content through the REST APIs.

Accessing the serial API over the serial line

To access the serial API over the serial line using the MACH10 Command Interface:

This tutorial describes how to access the serial API over the serial line and send a command.

  1. Set Line 1 Protocol to MACH10 Command Interface.
  2. Set MACH10 Line 1 Configuration to Enabled and enter the Project Tag.
  3. Use a terminal emulator (e.g. Tera Term) to connect the gateway.
  4. Send the following API command: mach10_getsettings. The API responds with the MACH10 settings, similar to:
{"project_tag":"MYSTQ_PT_778edaba-e7d5-4b5f-942d-0ef8f760f9cc",
"status_update_interval":"10",
"content_check_interval":"24"}

To access the serial API over the serial line using Mux commands:

This tutorial describes how to access the serial API over the serial line and send a command using Mux. See the Mux Reference for more detailed information about Mux commands and responses.

  1. Set Line 1 Protocol to Mux.
  2. Set Line Virtual_1 Protocol to MACH10 Command Interface.
  3. Set MACH10 Line Virtual_1 Configuration to Enabled and enter the Project Tag.
  4. Use a terminal emulator (e.g. Tera Term) to connect the gateway.
  5. Send the following API commands:
    1. 1v1. The API responds with K, indicating success.
    2. 1sb~. The API responds with 500K, indicating number of bytes allowed and success.
    3. mach10_getsettings~. The API responds with K, indicating success.
    4. 1p. The API responds with K, indicating success.
    5. 1rb~2000. The API responds with the MACH10 settings, similar to:
{"project_tag":"MYSTQ_PT_778edaba-e7d5-4b5f-942d-0ef8f760f9cc",
"status_update_interval":"10",
"content_check_interval":"24"}

Log in to MACH10 and click Help for more information about using the MACH10 Serial API.

MACH10 Device Status

MACH10 Device Status settings display details about the status of the MACH10 client activity with the MACH10 platform. Status details include when the device status was updated on the platform, when the client last checked for configuration and firmware updates, and what updates are available. If MACH10 has not yet been configured with the platform, the status displays an error state.

To view MACH10 device status:

  • In the Web Manager, go to MACH10 > Device > Status.
  • In the CLI, use Status MACH10 level to show the current status. See Status MACH10 level.
  • The XML statusgroup mach10 will display the state and available update status items. (In the CLI, issue xsr dump mach10 from the xml level.)

MACH10 Device Configuration

MACH10 Device Configuration settings allow you to configure the MACH10 client to associate with the MACH10 platform. These include how often the client sends status updates to the cloud, how often the client checks for content updates from the cloud, settings for firmware and configuration updates, device and server settings, as well as local port settings to use if bridging is enabled on the gateway.

To configure MACH10 Device settings:

MACH10 Device Configuration Settings

Setting Description
State Operational state of the MACH10 client on the device. May be Enabled or Disabled.
Status Update Interval The frequency that MACH10 updates device status to the cloud. Units can be minutes, hours, or days. The valid range is between 1 minute and 1 day (1440 minutes).
Content Check Interval The frequency that MACH10 checks the cloud for updates to configuration or firmware. Units can be minutes, hours, or days. The valid range is between 1 minute and 1 day (1440 minutes).
Apply Firmware Updates Allow firmware updates. May be Enabled or Disabled.
Apply Configuration Updates Setting to indicate when to apply configuration updates. Options are Never, If Unchanged, or Always. If Unchanged means that configuration updates will only be applied if the current configuration has not been modified locally.
Reboot After Configuration Update Setting to reboot the gateway after a configuration update. May be Enabled or Disabled. The device will always reboot after a firmware upgrade.
Device Name Device name may contain up to 63 characters.
Device Description Description may contain up to 63 characters.
Additional Logging Provide additional information in the Trouble Log. May be Enabled or Disabled.
Active Connection Specifies which connection parameters will be used in communication with the cloud. May be 1 or 2.
Connection 1 Parameters used in the first connection. When Edit is clicked, the following settings for Connection 1 appear: Domain, Local Port, MQTT State, MQTT Domain, MQTT Local Port. See below for more information on these fields.
Connection 2 Parameters used in the second connection. When Edit is clicked, the following settings for Connection 1 appear: Domain, Local Port, MQTT State, MQTT Domain, MQTT Local Port. See below for more information on these fields.
Domain Visible only when Connection 1 > Edit or Connection 2 > Edit is clicked. Domain may contain up to 63 characters. You should not change this value unless instructed to do so.
Local Port Visible only when Connection 1 > Edit or Connection 2 > Edit is clicked. Enter a specific port to receive forwarded packets. By default, the local port is random. To reset to random, blank the value in the field. If bridging is enabled, you must enter a non-random value for MACH10 to work properly.
MQTT State Visible only when Connection 1 > Edit or Connection 2 > Edit is clicked. Enables or disables MQTT to communicate with the cloud. May be Enabled or Disabled.
MQTT Domain Visible only when Connection 1 > Edit or Connection 2 > Edit is clicked. MQTT domain name. May contain up to 63 characters.
MQTT Local Port Visible only when Connection 1 > Edit or Connection 2 > Edit is clicked. Enter a specific port to receive forwarded packets. By default, the local port is random. To reset to random, blank the value in the field. If bridging is enabled, you must enter a non-random value for MACH10 to work properly.

MACH10 Line and Virtual Line Configuration

MACH10 Line 1, Line Virtual_1, and Line Virtual_2 Configuration settings provides line settings related to the MACH10 platform. You must configure these line settings in order to send serial API commands over the serial line (Line 1 or virtual lines).

To configure MACH10 Line settings:

MACH10 Line Configuration Settings

Setting Description
State Operational state of MACH10. May be Enabled or Disabled.
Project Tag Project tag identifies the name of the MACH10 cloud project that the device belongs to. May contain up to 63 characters.
Status Update Interval The frequency that MACH10 updates device status to the cloud. Units can be minutes, hours, or days. The valid range is between 1 minute and 1 day (1440 minutes).
Content Check Interval The frequency that MACH10 checks the cloud for updates to configuration or firmware. Units can be minutes, hours, or days. The valid range is between 1 minute and 1 day (1440 minutes).

Manage with Lantronix Gateway Central

Monitor and maintain your fleet of Lantronix IoT gateways using the Lantronix Gateway Central service. Lantronix Gateway Central is a secure, cloud-based device management service for Lantronix IoT gateways and is powered by MACH10.

Using Lantronix Gateway Central, you can easily do the following:

  • Monitor connectivity and performance of your fleet of gateways using dashboards, actionable insights, and configurable real-time alerts.
  • Configure your gateways remotely.
  • Group gateways by various properties.
  • Update your gateways' firmware remotely, scheduling per group if desired.