Configuring MQTT

MQTT Protocol Configuration

The MQTT (Message Queuing Telemetry Transport) protocol enables APEX to communicate securely with the BACSYS Platform or any third-party MQTT broker using a lightweight publish-subscribe messaging model. MQTT is commonly used for Industrial IoT (IIoT), real-time monitoring, telemetry, and cloud connectivity.

Configuring MQTT

Bax device details

  1. Navigate to the Protocol section.
  2. Click Add Protocol or New Protocol.
  3. From the Protocol drop-down list, select MQTT.

Bax device details

Select Platform

After selecting MQTT, choose the platform where the device will connect.

The available options are:

  • BACSYS Platform
  • Other Brokers

Bax device details

Option 1: BACSYS Platform

When BACSYS Platform is selected, enter the following details.

MQTT Configuration Fields

Bax device details

FieldDescription
Device NameEnter a unique name to identify the MQTT device. This name is registered on the BACSYS Platform. Duplicate device names are not allowed. If the entered name already exists, choose a different name before proceeding.
Device DescriptionEnter a brief description of the device. This helps users easily identify the purpose or location of the MQTT device.
Device TopicSpecify the MQTT topic used for publishing and subscribing to messages. The topic should follow your organization's naming convention to simplify device management.
Server IP / HostnameEnter the IP address or hostname of the MQTT Broker. Ensure that the APEX device can communicate with the broker over the network. When using the BACSYS Platform, the broker IP should match the platform configuration.
PortEnter the MQTT Broker port number. The default MQTT port is 1883, while 8883 is commonly used for secure TLS communication. Ensure that the port matches the broker configuration.
Organization IDEnter the Organization ID generated from the BACSYS Platform during device onboarding. This ID uniquely identifies your organization and is required for device authentication.
API KeyEnter the API Key generated from the BACSYS Platform. This key authenticates the APEX device when connecting to the MQTT Broker.
Secret KeyEnter the Secret Key generated along with the API Key. The Secret Key is used to securely authenticate the device with the BACSYS Platform. Keep this value confidential.
Device LatitudeEnter the geographical latitude of the device installation location. This information is optional but useful for mapping and asset management.
Device LongitudeEnter the geographical longitude of the device installation location. This information is optional but recommended for location tracking.
TLS EncryptionEnable this option to establish a secure encrypted MQTT connection using SSL/TLS certificates. When enabled, valid security certificates must be uploaded before the device can connect successfully.

Bax device details

Security Certificates

Bax device details

CertificateDescription
CA CertificateUpload the Certificate Authority (CA) certificate used to verify the identity of the MQTT Broker. This ensures that the device connects only to a trusted server.
Client CertificateUpload the client certificate issued for the APEX device. This certificate authenticates the device with the MQTT Broker during a secure TLS connection.
Client KeyUpload the private key associated with the Client Certificate. The Client Key is required to establish a secure and authenticated TLS connection. Keep this file secure and do not share it.

Note

  • The Device Name must be unique on the BACSYS Platform.
  • The Server IP/Hostname and Port must match the MQTT Broker configuration.
  • When TLS Encryption is enabled, uploading the CA Certificate, Client Certificate, and Client Key is mandatory.
  • The Organization ID, API Key, and Secret Key can be generated from the BACSYS Platform by navigating to Onboard APEX → Generate License.

Generating Organization ID, API Key, and Secret Key

Bax device details

Follow the steps below to obtain the required credentials from the BACSYS Platform.

  1. Log in to the BACSYS Platform.
  2. Navigate to the Onboard APEX section.
  3. Click Onboard APEX.
  4. The Onboard APEX dialog box appears.
  5. Click Generate License.
  6. The platform generates the following credentials:
    • Organization ID
    • API Key
    • Secret Key
  7. Copy these values.
  8. Return to the APEX application.
  9. Paste the copied values into their respective fields.

Bax device details

Uploading MQTT Certificates

To establish a secure MQTT connection, upload the required SSL/TLS certificates.

Steps

  1. Open File Explorer.
  2. Navigate to the following directory:
C:\Arcos\Backend\certs
  1. Locate the following certificate files:

    • CA Certificate
    • Client Certificate
    • Client Key
  2. In the APEX MQTT configuration page, upload each certificate into its corresponding field.

CertificateDescription
CA CertificateUsed to verify the identity of the MQTT Broker.
Client CertificateUsed to authenticate the APEX device with the MQTT Broker.
Client KeyThe private key associated with the Client Certificate for secure communication.

Important

Upload the correct certificate files. An invalid or mismatched certificate may prevent the MQTT connection from being established.


Export Device

After completing the MQTT configuration:

  1. Verify all the entered details.
  2. Click Export Device.
  3. Save the exported device configuration.
  4. The exported configuration can be imported into another APEX device if required.

Validation Checklist

Before saving the MQTT configuration, verify the following:

  • MQTT protocol is selected.
  • Correct platform (BACSYS Platform or Other Broker) is selected.
  • Device Name is unique.
  • Device Description is entered.
  • Device Topic is configured correctly.
  • Host/IP Address is reachable.
  • Port number matches the MQTT Broker configuration.
  • Organization ID is entered correctly.
  • API Key is entered correctly.
  • Secret Key is entered correctly.
  • CA Certificate is uploaded.
  • Client Certificate is uploaded.
  • Client Key is uploaded.
  • Device configuration has been exported successfully.

Option 2: Other Broker

Select Other Broker to connect the APEX device to a third-party MQTT Broker instead of the BACSYS Platform.

Bax device details

Configuration Fields

FieldDescription
Device NameEnter a unique name to identify the MQTT device.
Device DescriptionEnter a brief description of the MQTT device.
APEX Topic for PublicationEnter the MQTT topic used by the APEX device to publish data to the MQTT Broker.
Server IP / HostnameEnter the IP address or hostname of the MQTT Broker. Ensure the broker is reachable from the APEX device.
PortEnter the MQTT Broker port number. The default port is 1883 for MQTT and 8883 for secure MQTT over TLS.
Authentication SchemeSelect the authentication method required by the MQTT Broker. Available options are None, Basic, and X.509.

Authentication Scheme

None

Select None if the MQTT Broker does not require authentication.

Payload Format

When None is selected, the following payload format is available:

  • None

No additional credentials are required.


Basic

Bax device details

Select Basic if the MQTT Broker requires username and password authentication.

Payload Formats

The following payload formats are available:

  • Simple
  • UDMI
  • BMS Path

For all payload formats, provide the following credentials.

FieldDescription
UsernameEnter the username used to authenticate with the MQTT Broker.
PasswordEnter the password associated with the username.

X.509

Bax device details

Select X.509 to use certificate-based authentication.

Payload Formats

The following payload formats are available:

  • Simple
  • UDMI
  • BMS Path

For all payload formats, upload the required security certificates.

Security Certificates

CertificateDescription
CA CertificateUpload the Certificate Authority (CA) certificate used to verify the MQTT Broker.
Client CertificateUpload the client certificate issued for the APEX device.
Client KeyUpload the private key associated with the client certificate.

Adding Points to an MQTT Network

After successfully creating the MQTT network, you can add points that need to be published to the MQTT Broker or BACSYS Platform.

Steps to Add Points

Bax device details

  1. Navigate to the Protocol page.
  2. Select the MQTT network that you created.
  3. Open the MQTT network.
  4. Click Add Points.

The Add Points window displays all the available points configured in the APEX device.

  1. Select the required points that you want to publish.
  2. Click Export Points to include the selected points in the MQTT network.

Once the points have been added, they will be listed under the selected MQTT network. Bax device details

Exporting Points

After adding the required points:

Bax device details

  1. Verify that all the required points have been added.
  2. Click Export Point to export the selected points.
  3. Once the export is completed, click Start Export.

The APEX device begins publishing the exported points to the configured MQTT Broker or BACSYS Platform.

Note

The Start Export button must be clicked after exporting the points. Until Start Export is enabled, the selected points will not be published to the MQTT Broker or BACSYS Platform.

Stopping the Export

If you need to stop publishing the selected points to the MQTT Broker or BACSYS Platform, you can stop the export at any time.

Bax device details

Steps

  1. Open the required MQTT network.
  2. Click Stop Export.

The APEX device immediately stops publishing the configured points to the MQTT Broker or BACSYS Platform.

Note

Clicking Stop Export only stops the export process. The MQTT network configuration and the added points remain unchanged and can be exported again by clicking Start Export.

Deleting an MQTT Device

If the MQTT device is no longer required, you can delete it from the APEX application.

Bax device details

Steps

  1. Open the required MQTT network.
  2. Click Delete Device.
  3. Confirm the deletion when prompted.

The selected MQTT device is permanently deleted from the APEX application. All points associated with the device are also removed, and the device will no longer publish data to the configured MQTT Broker or BACSYS Platform.

Removing Exported Points

If you no longer want to export specific points, you can remove them from the MQTT network.

Bax device details

Steps

  1. Open the required MQTT network.
  2. Select the point(s) that you want to remove.
  3. The application displays the number of selected points.
  4. Click Remove Selected Points.
  5. Confirm the removal when prompted.

The selected points are removed from the MQTT network and will no longer be exported to the MQTT Broker or BACSYS Platform. The remaining points continue to be available in the MQTT network.