MQTT Push

MQTT push provides a lightweight and efficient way to receive real-time IoT data from Globe Tracker devices. When events occur, our system publishes messages to your specified MQTT broker and topic(s).

Setup Requirements

To receive MQTT push notifications, you need to provide us with:

• MQTT broker address (hostname/IP and port)
• Authentication credentials (if required by your broker)
• Ability to publish to the relevant topic(s)
• Support for JSON payloads

MQTT Configuration

Broker and Topic Configuration

You must provide the MQTT broker details and the topic(s) to which you want to receive events. All object types can be sent to the same topic, or you can specify distinct topics per object type.

Example topic structure:

• globe-tracker/events (all events)
• globe-tracker/events/location (location updates)
• globe-tracker/events/reeferdata (Reefer telematics)

Quality of Service (QoS)

We support configurable MQTT QoS levels:

• QoS 0: At most once (fire and forget)
• QoS 1: At least once (guaranteed delivery)
• QoS 2: Exactly once (highest reliability)

Contact us to configure the desired QoS level for your integration.

Authentication

We support several authentication methods for MQTT brokers:

• Username and password
• Client certificate authentication (TLS)
• Anonymous (if your broker allows it)

Provide us with the necessary credentials or certificates, and we will configure our system accordingly.

TLS/SSL Encryption

We recommend using TLS/SSL encryption for secure MQTT communication. Provide your broker’s CA certificate if required.

Object Types

Push services send objects from object-sync services.:

Asset

Represents an asset in the system.

Required fields:

• id (string): Unique identifier for the asset (global_id)
• name (string): Asset name/serial number
• ownerId (string): Owner/customer global ID
• whenCreated (string, date-time): ISO 8601 timestamp when the asset was created
• whenUpdated (string, date-time): ISO 8601 timestamp when the asset was last updated

Optional fields:

• boxId (string, nullable): Box global ID
• disabled (boolean): Whether the asset is disabled
• note (string, nullable): Optional note about the asset
• tags (array of strings, nullable): Array of customer tags associated with the asset

Location

Represents a GPS location record.

Required fields:

• id (integer, int64): Unique identifier for the location record
• assetId (string): Asset global ID
• ownerId (string): Owner/customer global ID
• whenCreated (string, date-time): ISO 8601 timestamp when the location was recorded (GPS time)
• latitude (number, double): GPS latitude coordinate
• longitude (number, double): GPS longitude coordinate

Optional fields:

• altitude (number, double, nullable): GPS altitude in meters
• speed (number, double, nullable): Speed in the unit configured for the asset
• heading (number, double, nullable): Heading/bearing in degrees (0-360)
• zoneId (string, nullable): Zone identifier where the location was recorded

SensorData

Represents sensor data from an asset.

Required fields:

• id (integer, int64): Unique identifier for the sensor data record
• assetId (string): Asset global ID
• ownerId (string): Owner/customer global ID
• sensorId (string): Sensor identifier
• sensorType (string): Type of sensor
• whenCreated (string, date-time): ISO 8601 timestamp when the sensor data was recorded
• value (string): Sensor value (can be string representation of number or text)
• type (string): Data type of the sensor value

Optional fields:

• when_received (integer, int64, nullable): Unix timestamp in milliseconds when the data was received

ReeferData

Represents reefer (refrigerated container) data.

Required fields:

• id (integer, int64): Unique identifier for the reefer data record
• assetId (string): Asset global ID
• ownerId (string): Owner/customer global ID
• whenCreated (string, date-time): ISO 8601 timestamp when the reefer data was recorded
• reeferClass (string): Class/type of reefer unit
• data (object): JSON object containing reefer-specific data payload (additionalProperties: true)

GensetData

Represents generator set (genset) data.

Required fields:

• id (integer, int64): Unique identifier for the genset data record
• assetId (string): Asset global ID
• ownerId (string): Owner/customer global ID
• whenCreated (string, date-time): ISO 8601 timestamp when the genset data was recorded
• gensetType (string): Type/model of genset
• data (object): JSON object containing genset-specific data payload (additionalProperties: true)

Optional fields:

• boxId (string, nullable): Box global ID

GtoemData

Represents GTOEM (Globetracker OEM) data.

Required fields:

• id (integer, int64): Unique identifier for the GTOEM data record
• assetId (string): Asset global ID
• ownerId (string): Owner/customer global ID
• whenCreated (string, date-time): ISO 8601 timestamp when the GTOEM data was created
• payloadType (integer, int32): Type identifier for the payload
• data (object): JSON object containing GTOEM-specific data payload (additionalProperties: true)

Optional fields:

• boxId (string, nullable): Box global ID
• when_received (integer, int64, nullable): Unix timestamp in milliseconds when the data was received

For complete schema definitions, you can download the full OpenAPI schema file for use in API documentation tools, code generation, or validation.

Additional Fields

Push services may add additional fields to the object-sync service objects in some cases. These fields are added by the push service infrastructure and are not part of the base object schema.

MQTT Push

MQTT push can optionally add an eventId field to the payload when configured:

• Configuration: Set MQTT_SET_EVENT_ID environment variable to the field name where the eventId should be injected
• Field: eventId (string, UUID) - The unique event identifier from the Flowcore event system
• Location: The eventId is added at the top level of the payload with the field name specified by MQTT_SET_EVENT_ID (default: eventId)

Example with eventId injection:

{
  "id": 12345,
  "assetId": "550e8400-e29b-41d4-a716-446655440000",
  "ownerId": "660e8400-e29b-41d4-a716-446655440001",
  "whenCreated": "2024-03-20T14:30:00Z",
  "latitude": 55.676098,
  "longitude": 12.568337,
  "eventId": "evt_550e8400-e29b-41d4-a716-446655440000"
}

Note: The eventId injection is optional and must be explicitly configured. Contact your Globe Tracker representative to enable this feature.

Message Format

All MQTT messages use JSON payloads. We support only single delivery mode for MQTT:

Single Event Delivery

Each event is published as a single JSON object. The payload contains the object from the object-sync service directly:

Example: Location object

{
  "id": 12345,
  "assetId": "550e8400-e29b-41d4-a716-446655440000",
  "ownerId": "660e8400-e29b-41d4-a716-446655440001",
  "whenCreated": "2024-03-20T14:30:00Z",
  "latitude": 55.676098,
  "longitude": 12.568337,
  "altitude": 10.5,
  "speed": 0,
  "heading": 90
}

Example: SensorData object

{
  "id": 12345,
  "assetId": "550e8400-e29b-41d4-a716-446655440000",
  "ownerId": "660e8400-e29b-41d4-a716-446655440001",
  "sensorId": "sensor-001",
  "sensorType": "temperature",
  "whenCreated": "2024-03-20T14:30:00Z",
  "value": "25.5",
  "type": "DECIMAL"
}

Acknowledgement and Delivery Semantics

MQTT acknowledgements depend on the configured QoS level:

• QoS 0: No acknowledgement required
• QoS 1: Requires PUBACK from the subscriber
• QoS 2: Requires PUBREC, PUBREL, and PUBCOMP handshake

We track delivery status based on MQTT protocol acknowledgements. For QoS 1 and 2, messages will be retried until acknowledged by the broker.

Error Handling and Retry Logic

• If the broker is unavailable, we will retry connection and message delivery using exponential backoff.
• For QoS 1 and 2, messages are retried until acknowledged.
• If a message cannot be delivered after multiple attempts, it is logged for monitoring and support follow-up.

Monitoring and Delivery History

We store detailed metadata for each MQTT delivery attempt, including:

• Timestamp of the attempt
• Topic name
• QoS level
• Delivery status (success/failure)
• Error details (if any)

Accessing Delivery History

You can access MQTT delivery history and logs in several ways:

Using the Flowcore CLI

To extract MQTT push logs for the last day:

flowcore stream https://flowcore.io/globe-tracker-aps/example-data/mqtt-push-results.0/created.0.stream \
  --no-live \
  -s 1d \
  --payload \
  --json

Using data-pump sdk

You can use the data-pump NPM package to retrieve results

Using the Dashboard

We provide a dashboard where you can:

• View MQTT delivery history
• Check delivery status and error logs
• Inspect payload contents
• Track retry attempts and final delivery status

Contact your Globe Tracker representative to get access to your dashboard.

Best Practices

1. Subscribe Promptly: Ensure your client subscribes to the relevant topic(s) as soon as possible
2. Use Appropriate QoS: Choose a QoS level that matches your reliability needs
3. Idempotency: Implement idempotent processing to handle potential duplicate deliveries
4. Monitor Connection: Reconnect promptly if the connection to the broker is lost
5. Secure Your Broker: Use TLS/SSL and strong authentication
6. Batch Processing: If supported, enable batch processing for higher throughput