Percepxion Client

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

To access the Serial API over the serial Line, configure the Line operating mode to "Percepxion Interface". This line mode provides a command interface to the Percepxion serial API.

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

Percepxion Serial API

The following commands are accessible through the Percepxion Serial API.

Command Description Gateway Action
percepxion_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.
percepxion_register<payload> This command registers the device with the Percepxion 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.
percepxion_status<auth_token>,<payload> This command sends the current device status to Percepxion. Use this command to send device attributes for the capabilities that the device supports. Send the status update using the REST API.
percepxion_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.
percepxion_download<auth_token>,<payload> Send a request to download the content file to the device. The request parameter includes the file info returned from Percepxion in the percepxion_update command. Send the request to download the content through the REST APIs.
percepxion_capability_exchange<auth_token>,<telemetry_host>,<payload> This command exchanges the capabilities of a device to Percepxion. The gateway exchanges the capabilities of a device with Percepxion through REST API.
percepxion_capability_selection<auth_token>,<telemetry_host>,<payload> This command sends the capability selection of a device to Percepxion. The gateway sends the capability selection of a device to Percepxion through REST API.
percepxion_telemetry_publish<auth_token>,<telemetry_host>,<payload> This command publishes the status of the groups or attributes of a device to Percepxion. The gateway publishes the attributes' values to Percepxion through REST API.

Accessing the serial API over the serial line

To access the serial API over the serial line using the Percepxion Interface:

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

  1. Set Line 1 Protocol to Percepxion Interface.
  2. Set Percepxion 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: percepxion_getsettings. The API responds with the Percepxion 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 Percepxion Interface.
  3. Set Percepxion 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. percepxion_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 Percepxion settings, similar to:
{"project_tag":"MYSTQ_PT_778edaba-e7d5-4b5f-942d-0ef8f760f9cc",
"status_update_interval":"10",
"content_check_interval":"24"}

Percepxion Device Status

Percepxion Device Status settings display details about the status of the Percepxion client activity with the Percepxion 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 Percepxion has not yet been configured with the platform, the status displays an error state.

To view Percepxion device status:

Percepxion Device Configuration

Percepxion Device Configuration settings allow you to configure the client to associate with the Percepxion 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 Percepxion Device settings:

Percepxion Device Configuration Settings

Setting Description
State Operational state of the Percepxion client on the device. May be Enabled or Disabled.
Status Update Interval The frequency that Percepxion 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 Percepxion 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.
Domain Domain may contain up to 63 characters. You should not change this value unless instructed to do so.
Local Port 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 Percepxion to work properly.
MQTT State Enables or disables MQTT to communicate with the cloud. May be Enabled or Disabled.
MQTT Domain MQTT domain name. May contain up to 63 characters.
MQTT Local Port 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 Percepxion to work properly.
Additional Logging Provide additional information in the Trouble Log. May be Enabled or Disabled.

Percepxion Line Configuration

Percepxion Line 1, Line SPP, and Line Virtual configuration settings pertain to the Percepxion management platform. Configure one of these lines to send serial API commands over the line (Line for serial, Line SPP for Bluetooth_SPP, or Line Virtual for Mux).

To configure Percepxion Line settings:

Percepxion Line Configuration Settings

Setting Description
State Operational state of Percepxion. May be Enabled or Disabled.
Project Tag Project tag identifies the name of the Percepxion project that the device belongs to. May contain up to 63 characters.
Status Update Interval The frequency that Percepxion 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 Percepxion 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).