Network Services¶
In addition to providing a IPv4 networking stack, xPico 200 series of gateways also includes support for a number of networking protocols and services that deliver a complete network communications offload engine in network co-processor mode. The production ready services work together in wireless microcontroller mode to minimize required application development.
You can configure, start, and stop the clients and servers using the available management interfaces.
- DHCP Client
- DHCP Server
- DNS Client
- DNS Server
- TCP Client
- TCP Server
- HTTP(S) Server
- UDP
- SNTP Client
- SMTP Client
- TLS Client
- TLS Server
- Discovery
- CLI Server
- Bluetooth Client
- MACH10 Client
DHCP Client¶
The DHCP client obtains an IP address and other networking parameters when attempting to make a connection on either the wlan0 or eth0 interfaces. Configure the DHCP client for the wlan0 or eth0 interfaces by accessing the network interface configuration group for the respective interface.
By default, the wlan0 and eth0 interfaces are configured for DHCP mode versus static IP mode.
In Web Manager, go to Network and select eth0 > Interface > Configuration or wlan0 > Interface > Configuration.
For the CLI, see Config Interface level.
For XML, see configgroup interface.
DHCP Server¶
The DHCP server assigns an IP address to a client attempting to make a connection on the ap0 interface.
Enable the ap0 interface in order for the DHCP server to assign IP addresses to clients connecting on ap0.
In Web Manager, go to Network and select ap0 > Interface > Configuration.
For the CLI, see Config Interface level.
For XML, see configgroup interface.
DNS Client¶
The DNS client resolves and caches the DNS domain name to IP address mapping.
It communicates with the DNS server addresses configured statically or obtained via DHCP within the wlan0 or eth0 interface.
You can configure the Primary DNS and Secondary DNS to define the DNS servers that will be used when performing a domain name lookup.
In Web Manager, go to Network > eth0 or wlan0 > Interface > Configuration.
For the CLI, go to Config Interface level.
For XML, go to configgroup interface.
DNS Server¶
The DNS performs a redirect when the WLAN client connected to the SoftAP interface issues a DNS request. DNS resolves the request to the SoftAP IP address.
HTTP(S) Server¶
The HTTP server is used to store, process, and deliver web pages to the Web UI client using HTTP. It also serves resources such as HTML pages, Javascript files, images, etc. to web browser based applications or network applications that utilize the HTTP protocol for communication.
The HTTP server can be configured with TLS to provide secure HTTP communication.
HTTP Server Configuration¶
You can configure the following HTTP Server settings:
- Set the operation mode. The HTTP server can be enabled, disabled, or triggered by the CPM role. For details on configurable pins, see CPM.
- Specify the TLS credential to be used. For details on TLS credentials, see TLS Credentials.
- Set the authentication timeout value if Digest Authentication is in use.
- Specify the Inactivity Timeout for Standby Power mode. For details on managing power settings, see Power Management.
To configure the HTTP server:
In Web Manager, go to HTTP Server > Configuration.
In CLI, see Config HTTP Server Level.
In XML, see configgroup http server.
HTTP Server Configuration Settings¶
The following table describes the Web Manager HTTP Server configuration settings.
Links to the equivalent settings for the CLI and XML reference are listed below.
In CLI, see Config HTTP Server Level.
In XML, see configgroup http server.
Changes to HTTP Server take effect after reboot.
| HTTP Settings | Description |
|---|---|
| Mode | Enables or disables the HTTP server. Choices are: Enabled Disabled Triggered - HTTP Server will wait for the CPM Role to become active. Then the HTTP server stays up indefinitely. |
| Port | HTTP server port number. Default is 80. Clearing the field will restore the default. Enter 0 for none. |
| Secure Port | Secure port number. Enter 0 for none. The default Secure Port (TLS) can be overridden. |
| Secure Credential | TLS server credential. It may contain up to 30 characters. The secure credential specifies the name of the TLS Server Credential to be used for the secure connection. |
| Authentication Timeout | The Authentication Timeout value is applied only if Digest authentication is being used. |
| Inactivity Timeout | The amount of time the HTTP server will hold power on after completing a request. This setting only applies if HTTP Server is enabled in Power settings. The HTTP Server will hold power on this long after it completes a request. |
HTTP Server Security Access Control¶
HTTP Server security provides role-based access control enabling you to assign authentication directives to specific URIs. You can control access to built-in URIs, such as "/tlog" or "/upgrade", or ones that you create, such as a "/welcome" URI.
To assign access control to specific URIs, you specify the authentication type (what type of passphrase is required) and the user level (Admin, Tech, or User). The access control is hierarchical; Admin can access URIs assigned to Admin or below, while Tech can access URIs assigned to Tech or User level, and User can only access URIs granted to User level. Additionally, the Tech user level can only see URIs associated with their assigned Zone(s). See User Management for more details on zones.
The permission settings of a URI are passed on to the child folders of that URI, unless you set a different permission directive for a child folder. The directive will override the parent folder's access control setting.
Built-in URIs
The following URIs are built in to the server:
| URI | Description |
|---|---|
| /ajax | Web Manager |
| /fs | File System Web API |
| /logout | Digest Authentication |
| /mux_http | Mux Listener |
| /tlog | Trouble Log |
| /upgrade | Firmware Upgrade |
| /export/status | Export status |
| /export/config | Export configuration |
| /import/config | Import configuration |
| /action/status | Web API actions |
To configure HTTP server security access control:
- Enter a URI, starting with / and configure the authentication type and user level.
- If you have not created a Tech level user or User level user, do so now. See User Management for details.
- If necessary, create the URI and add an html file to the file system. See File System. If you configured access control on a built-in URI, you can skip this step.
- Test the authorization levels by pointing the browser to the specified URI (
/URI) and logging in with the appropriate user level.
For Web Manager, go to HTTP Server > Security.
For CLI, see Config HTTP Server Security Level.
For XML, see configgroup HTTP Server Security.
SNTP Client¶
The Simple Network Time Protocol (SNTP) client synchronizes with the Network Time Protocol (NTP) server. NTP is an Internet protocol used to synchronize computer clocks to a single time reference.
You can configure the Clock settings to update according to NTP or to update manually. For information on how to set the clock, see Date and Time.
You can also view and set the SNTP client configuration. See NTP.
SMTP Client¶
The Simple Mail Transfer Protocol (SMTP) client is used to configure an email message to be sent using an external SMTP server.
The SMTP client is available only through the CLI. To configure an email message, see Status SMTP level.
Example usage follows:
Send <ssl server hostname>
<username>
<password>
<from mail address>
<first recipient mail address>
[optional second recipient mail address]
[...] <-- Empty line ends recipient list
<subject>
<first line of body>
[optional second line of body]
[...] <-- Empty line ends body
TCP Client¶
The TCP client initiates a Tunnel connection with a TCP server that is listening on a designated port for a request.
TCP connections can use AES or TLS to encrypt the data stream. To configure the connection using either of these encryption types, you will need to supply an AES credential or TLS credential.
To configure TCP connections, see TruPort Serial.
TCP Server¶
The TCP server accepts Tunnel connection requests initiated by a TCP client.
TCP connections can use AES or TLS to encrypt the data stream.To configure the connection using either of these encryption types, you will need to supply an AES credential or TLS credential.
To configure TCP connections, see TruPort Serial.
UDP Client and Server¶
User Datagram Protocol (UDP) can be used to provide an alternative transport-layer protocol for Tunnel connections.
You can configure Tunnel to use UDP protocol. The reception setting can be "restricted" or "unrestricted." When it is set to "restricted," UDP packets will only be accepted from the address and port designated by the Host Address and Port. The remote address and port of the first received packet are taken as designated until the socket is closed. When it is set to "unrestricted," UDP packets from any IP address will be accepted as long as they are directed to the local Port.
To configure UDP, see TruPort Serial.
TLS Client¶
TLS can be configured for TCP tunnel connections or Socket (Mux).
TLS can be configured with HTTP to provide a secure HTTP server. For details on setting up TLS with HTTP, see HTTPS Server.
To configure TLS, you create a TLS credential that contains the security details such as the certificate, private key, and trusted authority, as needed.
The TLS protocol version must be one of the following combinations:
- TLS 1.0
- TLS 1.1
- TLS 1.2
- TLS 1.1, TLS 1.2
- TLS 1.0, TLS 1.1, TLS 1.2
To set up a TLS client for a tunnel or Mux connection, specify the TLS credential as part of the connection settings.
See TruPort Serial or TruPort Socket for details on how to set up these connections.
TLS Server¶
TLS can be configured for TCP tunnel connections or Socket (Mux).
To configure TLS, you create a TLS credential that contains the security details such as the certificate, private key, and trusted authority, as needed.
The TLS protocol version must be one of the following combinations:
- TLS 1.0
- TLS 1.1
- TLS 1.2
- TLS 1.1, TLS 1.2
- TLS 1.0, TLS 1.1, TLS 1.2
To set up a TLS server for a TruPort Serial (tunnel) or TruPort Socket (Mux) connection, specify the TLS credential as part of the connection settings.
See TruPort Serial or TruPort Socket for details on how to set up these connections.
Network Discovery¶
Network discovery allows applications on the network to discover the xPico 200 series gateway. An application such as DeviceInstaller issues discovery queries according to the Lantronix Discovery Protocol operating on UDP port 30718 (0x77FE).
To allow applications to discover the device, you enable the Discovery Query Port parameter for the network interface instances. Discovery is enabled by default.
To prevent applications from discovering the device, you disable the Query Port parameter for the network interface instances.
In Web Manager, go to Discovery > ap0 or eth0 or wlan0 > Configuration. Enable or disable the query port state.
For the CLI, see Config Discovery level.
For XML, see configgroup Discovery.
CLI Server¶
The CLI Server allows you to access the command mode remotely over the network using Telnet. By default, the CLI Server is disabled and remote access to the command line is not available. To connect using Telnet, the CLI server must be enabled in the configuration.
To configure the CLI Server:
In Web Manager, go to CLI Server > Configuration.
For CLI, see Config CLI Server Level.
For XML, see configgroup CLI Server.
Bluetooth Client¶
The Bluetooth client allows you to provision the gateway with configuration settings using the mobile gateway provisioning application. With Bluetooth enabled, you can use your mobile device to connect to the gateway, download and configure settings.
To enable/disable Bluetooth:
In Web Manager, go to Bluetooth > Configuration.
For CLI, see Config Bluetooth level.
For XML, see configgroup Bluetooth.
MACH10 Client¶
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).
To use the SDK to implement a line protocol to interpret data received on the line in terms of MACH10 Serial API commands, refer to the Sample Applications section in the xPico SDK User Guide.
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.
- Set Line 1 Protocol to MACH10 Command Interface.
- Set MACH10 Line 1 Configuration to Enabled and enter the Project Tag.
- Use a terminal emulator (e.g. Tera Term) to connect the xPico 200 series gateway.
- 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.
- Set Line 1 Protocol to Mux.
- Set Line Virtual_1 Protocol to MACH10 Command Interface.
- Set MACH10 Line Virtual_1 Configuration to Enabled and enter the Project Tag.
- Use a terminal emulator (e.g. Tera Term) to connect the xPico 200 series gateway.
- Send the following API commands:
1v1. The API responds withK, indicating success.1sb~. The API responds with500K, indicating number of bytes allowed and success.mach10_getsettings~. The API responds withK, indicating success.1p. The API responds withK, indicating success.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:
- In the Web Manager, go to MACH10 > Device > Configuration. See MACH10 Device Configuration Settings below for field descriptions.
- In the CLI, use config MACH10 Device level. See Config MACH10 Device level
- Use the XML configgroup mach10 device to import MACH10 Device configuration. See configgroup mach10 device
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. |
| 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 MACH10 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 MACH10 to work properly. |
| Additional Logging | Provide additional information in the Trouble Log. May be Enabled or Disabled. |
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:
- In the Web Manager, go to MACH10 > Line > Configuration. See MACH10 Line Configuration Settings below for field descriptions.
- In the CLI, use config MACH10 Line level. See Config MACH10 Line level
- Use the XML configgroup mach10 line to import MACH10 Line configuration. See configgroup mach10 line
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). |