MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks. The design principles are to minimise network bandwidth and device resource requirements whilst also attempting to ensure reliability and some degree of assurance of delivery. These principles also turn out to make the protocol ideal of the emerging “machine-to-machine” (M2M) or “Internet of Things” world of connected devices, and for mobile applications where bandwidth and battery power are at a premium.

Check the official MQTT website (http://www.mqtt.org) for more details on the protocol.

AWARE has a built-in MQTT client, which you can use to exchange context with other devices, remotely manage sensors or issue ESMs questionnaires on devices. We have tested AWARE with IBM’s RSMB MQTT server and Mosquitto (what is now used in AWARE’s dashboard), but other options do exist in the official MQTT website.

AWARE only supports one active MQTT connection. If you are part of a study, you’ll be connected to AWARE’s MQTT server automatically.

AWARE supports message persistence, both on the server and mobile phone. In other words, if the device or the server is unreachable, the messages are queued locally for delivery at a later time. By default, we enforce a QoS (Quality of Service) of level 2 (each message is delivered exactly once), but you can also have level 0 (no guarantee of message delivery) or level 1 (message is delivered at least once). By default, when activating the AWARE’s MQTT client, it subscribes to three topics (broadcasts, esm, and configuration), under its own AWARE Device ID. They offer the following functionalities:

• AWARE Device ID/broadcasts: receives broadcast actions and broadcasts on the device.
• AWARE Device ID/esm: queues an ESM, using a ESM definition.
• AWARE Device ID/configuration: remotely activate/deactivate sensors.

Settings

• Aware_Preferences.STATUS_MQTT: true or false to activate or deactivate MQTT client.
• Aware_Preferences.MQTT_SERVER: the URL/IP of the server.
• Aware_Preferences.MQTT_PORT: the connection port of the server. The standard TCP/IP ports for MQTT: 1883 (non-SSL, non-secure), 8883 (SSL, secure).
• Aware_Preferences.MQTT_USERNAME: the username to connect to the MQTT Server.
• Aware_Preferences.MQTT_PASSWORD: the password to connect to the MQTT Server.
• Aware_Preferences.MQTT_KEEP_ALIVE: how frequently to ping the server to keep alive the connection, in minutes (default is every 5 minutes).
• Aware_Preferences.MQTT_QOS: the QoS expected for message delivery (2=exactly once, 1=at least once, 0=no guarantee).

• Mqtt.ACTION_AWARE_MQTT_MSG_RECEIVED: broadcasted when there is a new MQTT message. Contains two extras:
  • Mqtt.EXTRA_TOPIC: a string with the message topic.
  • Mqtt.EXTRA_MESSAGE: a string with the message published. This can be also JSON strings.
• Mqtt.ACTION_AWARE_MQTT_MSG_PUBLISH: received broadcast to publish a message to MQTT. Two extras are required when issuing this broadcast:
  • Mqtt.EXTRA_TOPIC: a string with the target topic to publish into.
  • Mqtt.EXTRA_MESSAGE: a string with the message to be published. This can be also JSON strings.
• Mqtt.ACTION_AWARE_MQTT_TOPIC_SUBSCRIBE: received broadcast to subscribe to a specific topic. One extra is required when issuing this broadcast:
  • Mqtt.EXTRA_TOPIC: a string with the target topic to subscribe to.
• Mqtt.ACTION_AWARE_MQTT_TOPIC_UNSUBSCRIBE: received broadcast to unsubscribe from a specific topic. One extra is required when issuing this broadcast:
  • Mqtt.EXTRA_TOPIC: a string with the target topic to unsubscribe from.

Mqtt Messages

Contains the exchanged messages.

Mqtt_Messages.CONTENT_URI
content://com.aware.provider.mqtt/mqtt_messages

Mqtt Subscriptions

Contains the subscribed MQTT topics.

Mqtt_Subscriptions.CONTENT_URI
content://com.aware.provider.mqtt/mqtt_subscriptions

Intent message = new Intent(ACTION_AWARE_MQTT_MSG_PUBLISH);
message.putExtra(Mqtt.EXTRA_TOPIC, "xxx/");
message.putExtra(Mqtt.EXTRA_MESSAGE, "hello world");
sendBroadcast(message);

Intent message = new Intent(ACTION_AWARE_MQTT_MSG_PUBLISH);
message.putExtra(Mqtt.EXTRA_TOPIC, "xxx/configuration");
message.putExtra(Mqtt.EXTRA_MESSAGE, "ACTION_AWARE_ACCELEROMETER=true;FREQUENCY_ACCELEROMETER=3");
sendBroadcast(message);

Intent message = new Intent(ACTION_AWARE_MQTT_MSG_PUBLISH);
message.putExtra(Mqtt.EXTRA_TOPIC, "xxx/esm");
message.putExtra(Mqtt.EXTRA_MESSAGE, "[{'esm':{'esm_type':1,'esm_title': 'What is for dinner?', 'esm_instructions': 'I will be home soon!','esm_submit': 'OK', 'esm_expiration_threashold': 0, 'esm_trigger': 'Testing'}}]");
sendBroadcast(message);

Intent message = new Intent(ACTION_AWARE_MQTT_MSG_PUBLISH);
message.putExtra(Mqtt.EXTRA_TOPIC, "xxx/broadcasts");
message.putExtra(Mqtt.EXTRA_MESSAGE, "ACTION_AWARE_CUSTOM_BROADCAST");
sendBroadcast(message);