The message hub is a way to communicate between multiple instances of Amy or even between multiple parts of one instance.

Currently the backend for this is MQTT, so for running Amy you need to have a MQTT Broker on your System. The path of the broker defaults to tcp://localhost and can be configured in the mqtt.config.properties file.

Communication via Message Hub

The message hub in the framework is a programatic API to publish and subscribe to topics using MQTT.

Take a look at the MQTT Standard to get an overview of topics, QoS etc. If your not familiar with it already.

Take note that we do not support leading / for example /smarthome/location/room is not supported.

We restrict first topic levels to the following system level topics:

• smarthome
• system
• user
• info

System Level Topics

smarthome

smarthome/{location}/{room}/{function}

Examples:

• smarthome/home/kitchen
• smarthome/home/

The 2nd and 3rd topic levels specify the location like this: smarthome/location/room

Every topic level after this can be used as desired.

system

tba

user

user/{user}/{topic}

Example:

• user/Max/notification

The 2nd topic levels specify the user. This can be done by a unique user identifier, the user name, the real name, an alias, the email, ...

Because of the variety of the connected MQTT devices there can't be a centralized user management. Each topic must define how users are identified in its domain.

info

tba

MessageHub

The MessageHub is a programatic API to publish and subsribe to topics.

Message Receiver

Example of a MessageReceiver that can be implemented by plugins. The Subscription is active after loading a plugin. MessageReceiver can use Services form the DI, so it can use the MessageHub to publish new messages.

@MessageReceiver
public class Example {

	@Reference
	private MyService service;

	@Subscription("smarthome/+/+/music/play")
	public void playMusic(String message, TopicName topic) {
		...
		if (room.equals("all")) {
			this.service.play();
		} else {
		...
	}
	
	@Subscription("user/+/mails")
	public void notification(String message, TopicName topic) {
	
	...
	}

}

Message receivers are components which have access to Services with the @Reference. Message receivers have request scope, so for each request(message) a new instance is created.