Configuration
A DD500E configuration is created by making required adjustments to a template file containing all relevant parameters. The created configuration is uploaded to the DD500E, using a command driven Configuration Application. The application and default configuration template files can be downloaded from the Advenica Artifactory file share site, see Downloads for details.
Even if both the UDP and MQTT protocols are supported by the DD500E, only one protocol can be utilized at a time. This means that the device must be updated with a protocol specific firmware whenever a protocol switch is required, as described in Switching protocols. Make sure the device is running the apropriate firmware for the intended usage before proceeding with configuration. The device comes preloaded with the firmware for UDP.
Make sure the following files are downloaded before proceeding:
- dd500e_config.exe
- dd500e_config_template-udp-vX.Y.Z.toml if the UDP protocol is to be used
- dd500e_config_template-mqtt-vX.Y.Z.toml if the MQTT protocol is to be used
Preparations
Perform the following steps to prepare for using the Configuration Application:
Editing configuration for UDP usage
The UDP service is made up of two components, a UDP server running on the Upstream side and a UDP client running on the Downstream side of the DD500E.
The server reads incoming UDP datagrams and directly forwards only the payload of each datagram to the Downstream client.
A complete UDP configuration includes network settings for both the Upstream and Downstream side of the device. Multiple configurations can be created, using unique names when saved. Only one configuration file can be uploaded to the DD500E and the file must have the .toml file extension to be accepted when uploaded to the device.
- DD500E comes prepared for UDP service usage.
- DD500E is delivered without any loaded configuration.
- DD500E does not support dynamic configuration, such as DHCP.
Configuration steps
Default UDP settings
In the DD500E default dd500e_config_template-udp-vX.Y.Z.toml configuration file, the following parameters are available:
| Parameter | Default value | Comment |
|---|---|---|
| Upstream | ||
| upstream_ip | 10.0.0.42 | IPv4 address for the Upstream network interface. |
| upstream_network_mask | 255.255.255.0 | IPv4 network mask for the Upstream network interface. |
| upstream_port | 6000 | UDP port the Upstream network interface will listen on. |
| Downstream | ||
| downstream_ip | 10.0.0.54 | IPv4 address for the Downstream network interface. This address will be used as source address for packets sent to the intended destination. |
| downstream_network_mask | 255.255.255.0 | IPv4 network mask for the Downstream network interface. |
| downstream_default_gateway_ip | 0.0.0.0 | IPv4 address for the default gateway on the Downstream network. If set to 0.0.0.0, no default gateway will be set and the destination_ip must be in the same subnet as downstream_ip. |
| destination_ip | 10.0.0.2 | Destination IPv4 address to forward data to. |
| destination_port | 6000 | Destination UDP port to forward data to. |
| Common | ||
| max_payload_size | 1472 | Maximum size, in bytes, of payload within a UDP datagram. A lower value makes the device able to handle more datagrams per second. Minimum value is 32. Maximum value is the smallest of: - connected network Ethernet MTU minus 28 (to accommodate IP and UDP headers) - 1472 Note! IP fragmentation or Path MTU Discovery (PMTUD) is not supported. |
Editing configuration for MQTT usage
The MQTT service enables message passing over the DD500E. It connects to a broker on the Upstream (source) network and copies messages, regardless of topic, to a broker on the Downstream (destination) network. Connections to both Upstream and Downstream brokers are made using QoS 0 (fire and forget, messages are sent just once without confirmation).
- Max transfer rate ~22Mbps (2000pps) when not using TLS.
- Max transfer rate ~7Mbps (600pps) when using TLS.
- When using TLS, DD500E only verifies that the certificate presented by the broker is signed by the configured CA certificate.
- Max size on topic + message is 1472.
- Messages larger than 55kb will cause the DD500E to stop. Manual restart is required.
A complete MQTT configuration includes network settings for both the Upstream and Downstream side of the device. Multiple configurations can be created, using unique names when saved. Only one configuration file can be uploaded to the DD500E and the file must have the .toml file extension to be accepted when uploaded to the device.
- DD500E comes prepared for UDP service usage. To use the MQTT service, a protocol switch must be performed.
- DD500E is delivered without any loaded configuration.
- DD500E does not support dynamic configuration, such as DHCP.
Supported versions
The following versions of respective protocols are supported by the MQTT service:
| Protocol | Supported version(s) |
|---|---|
| MQTT | 3.1.1 |
| TLS | 1.2 |
Configuration steps
Default MQTT settings
In the DD500E default dd500e_config_template-mqtt-vX.Y.Z.toml configuration file, the following parameters are available:
| Parameter | Default value | Comment |
|---|---|---|
| Upstream | ||
| upstream_ip | 10.0.0.42 | IPv4 address for the Upstream network interface. |
| upstream_network_mask | 255.255.255.0 | IPv4 network mask for the Upstream network interface. |
| upstream_mqtt_broker_ip | 10.0.0.2 | IPv4 address of the MQTT broker the Upstream side of the DD500E will connect to. |
| upstream_mqtt_broker_port | 1883 | TCP port number of the MQTT broker the Upstream side of the DD500E will connect to. |
| upstream_mqtt_client_identifier | DD500E-upstream | Client identifier presented by the Upstream side of the DD500E in the CONNECT packet sent to the MQTT broker it connects to. The identifier's length must be between 1 and 23 characters. The broker may further restrict the length and set of allowed characters. |
| upstream_tls_ca_certificate_file | (empty) | If set, the Upstream side of DD500E will connect to the MQTT broker using MQTT over TLS. If empty, TLS will not be used. If set, the entered value must be the path to a file with a certificate for the CA that issues TLS certificates for the broker on the Upstream side. The file must be in PEM format and contain a single certificate. Store the certificate file locally on the Configuration laptop, typically in the same directory as the dd500e_config.exe file. Parameter example: 'C:\DD500E\certificate_file.pem'. |
| Downstream | ||
| downstream_ip | 10.0.0.54 | IPv4 address for the Downstream network interface. This address will be used as source address for packets sent to the intended destination. |
| downstream_network_mask | 255.255.255.0 | IPv4 network mask for the Downstream network interface. |
| downstream_default_gateway_ip | 0.0.0.0 | IPv4 address for the default gateway on the Downstream network. If set to 0.0.0.0, no default gateway will be set and the destination_ip must be in the same subnet as downstream_ip. |
| downstream_mqtt_broker_ip | 10.0.0.2 | IPv4 address of the MQTT broker the Downstream side of the DD500E will connect to. |
| downstream_mqtt_broker_port | 1884 | TCP port number of the MQTT broker the Downstream side of the DD500E will connect to. |
| downstream_mqtt_client_identifier | DD500E-downstream | Client identifier presented by the Downstream side of the DD500E in the CONNECT packet sent to the MQTT broker it connects to. The identifier's length must be between 1 and 23 characters. The broker may further restrict the length and set of allowed characters. |
| downstream_tls_ca_certificate_file | (empty) | If set, the Downstream side of DD500E will connect to the MQTT broker using MQTT over TLS. If empty, TLS will not be used. If set, the entered value must be the path to a file with a certificate for the CA that issues TLS certificates for the broker on the Downstream side. The file must be in PEM format and contain a single certificate. Store the certificate file locally on the Configuration laptop, typically in the same directory as the dd500e_config.exe file. Parameter example: 'C:\DD500E\certificate_file.pem'. |
Using Configuration Application
The Configuration Application is command driven and will perform various tasks based on entered commands.
Available commands are:
- list-ports - lists available serial ports. The command requires that the USB-serial cables are connected correctly (see Connecting cables for configuration) and that the DD500E is powered on (see Power).
- configure - sends a configuration file to the specified serial ports.
- info - shows device specific information from a specified serial port (see Info).
- diagnostics - shows diagnostic information from a specified serial port (see Diagnostics).
- error-logs - shows the 10 latest error logs from a specified serial port (see Error logs).
- read - reads real-time information from a specified serial port. Note that network traffic sent over the DD500E cannot be accessed in any way.
- firmware-upgrade - sends new firmware to the specified serial ports. Both the Upstream and Downstream section of the DD500E must be upgraded at the same time (see Firmware upgrade).
- factory-reset - erases all user provided settings (see Factory reset).
- help - provides information about all commands or a specified command.
To start the Configuration Application, perform the following steps:
Checking COM ports
Due to the way that Windows handles connected USB-serial ports, it is necessary to determine which COM ports that has been assigned when the Configuration ports on the DD500E have been connected to the Configuration laptop.
To determine COM port assignment, perform the following steps:
Uploading configuration
The following instruction assumes that a customized configuration has been created. See Editing configuration for UDP usage or Editing configuration for MQTT usage for further information.
To upload a configuration, perform the following steps:
Verifying configuration
To verify the configuration after upload, perform the following steps: