GS MQTT (Beta)

End Points	X.509 Certificates and Policies	Monitoring and Testing	The Date and Times
MQTT API	MQTT v5.0 Conventions	Examples	Time Zones
Limits	GS Conventions		IDs and UIDs

Overview

MQTT (Message Queuing Telemetry Transport) is a standards-based messaging protocol ideal for machine-to-machine communication especially when power and computing is constrained. GoveStreams has its own set of MQTT servers supporting the latest MQTT v5.0 specification.

End Points

GroveStreams MQTT is running as a cluster of paired servers with each pair being a primary and backup server. This configuration provides maximum scalability with high availability.

Most MQTT clients allow for the setting of multiple server URIs. For example, the popular MQTT client, Eclipse Paho, supports passing in an array of server URIs with the setServerURIs(String[] array) method on the MqttConnectOptions class.

Assign GroveStreams' server URIs in an order that supports starting with the primary and then switching to the backup. Switch to the next pair of servers when both the primary and backup fail. A Paho example of this would be passing in the server URIs in an order to attempt re-connections when connections are dropped: Where the 'b' connections are the backups.

Today, GroveStreams has only one pair of MQTT servers. More pairs will be added as needed in the future.

Available Connection Points:

• mqtt1.grovestreams.com: Primary
• mqtt1b.grovestreams.com: mqtt1's high availability, shared state backup

Port:

• 8883

Supported MQTT v5.0 Conventions

• Quality of Service (QoS) options:
• At Most Once: 0
• At Least Once: 1
• Exactly Once: 2
• Persistent Sessions
• Retained Messages. Up to 60 days maximum, regardless of what the client message ExpiryInterval is set to. We set this arbitrary value to prevent messages from being retained forever and impacting server scalability.
• User Properties
• Response Topic
• Last Will and Testament (LWT). The certificate chain used during the creation of the LWT is stored and applied when the LWT is activated. The client must update the LWT when any part of the certificate chain has changed.
• Subscription Wildcards (# *):
  • Any words. Multi level: #
    • Adding this wildcard to an address would match all branches of the address hierarchy under a specified node. For example: /uk/# Would match /uk/cities, /uk/cities/newcastle and also /uk/rivers/tyne.
  • Single word. Single level: *
    • Matches a single level in the address hierarchy. For example /uk/*/stores would match /uk/newcastle/stores but not /uk/cities/newcastle/stores
• Link Stealing is not allowed. Whenever a new client connects with the same client ID as another existing client then the new client’s session will be closed and its network connection will be terminated

GroveStreams Conventions

• MQTT Client IDs are required and must be unique within each GS organization.
• X.509 Certificates are required for client connections. MQTT passwords are not allowed. More information can be found on the GS MQTT Certificates page.
• All topics must start with an organization UID. The only exception is manage/cert/myorg/cid/{compId} which is used to retrieve the organization UID that the call's certificate is registered within.
• Wildcards are not allowed for publishes.
• Most MQTT Exceptions, raised by GroveStreams, are logged as System Notifications and the MQTT client connection will be closed.
• GroveStreams reserves some topics. That is, GroveStreams subscribes to some topics and processes them when a publish occurs. It can publish other topics during Certificate Operations. See the MQTT API page for more information.
• Most GroveStreams HTTP APIs can be called with a GS reserved topic. See the MQTT API page for a list of reserved GS topics including the HTTP API Topic.
• IDs and UIDs
• Date and Times

Limits

• Maximum Publishes per Minute per client: 30.
• Flow Control is when a broker can tell a client how many QoS 1 & 2 messages it can receive before being acknowledged and vice versa. The amount is 50.
• Topic Alias Maximum: 100
• Maximum Packet Size: 1,048,576 bytes
• Server Keep Alive: 20 minutes. The primary use of the server keep alive is for the server to inform the client that it will disconnect the client for inactivity sooner than the keep alive specified by the client.
• Default Session Expiry Interval: 10 seconds. This applies to clients using cleanStart set to false. The broker will use the client’s session expiry interval if it is set. If it is not set then the broker will apply this value. This value is low to force clients to set an expiry interval.
• Maximum SessionExpiry: 7 Days
• Maximum Subscriptions Per Client: 50
• Maximum Message Size: 10 MBs
• Maximum Topic Levels: 15. Example: /orgUid/level2/level3/level4/level5/level6/level7/level8/level9/level10/level11/level12/level13/level14/level15

Examples

• Raspberry Pi MQTT Tutorial
• Raspberry Pi MQTT Tutorial Extras

Monitoring and Testing

• The user must have Execute access rights to the selected certificate.
• Watch for System notifications while troubleshooting to see detailed error messages.
• The tool utilizes web sockets to communicate with GS web servers which then connect with a GS MQTT server while adhering to the selected certificates' policy.