Modules

Modules

Modules are the heart of this application. They define the commands that are allowed and they define which action to take once the correct commands are spoken. They also take care of all of the context-based logic.

Modules are hard-coded in Java. You can still add your own, but in most of the cases configuring the existing ones will be sufficient. Modules can be instanced multiple times. All instances are completely independent from each other, with each having a unique name and configuration.

In your config.json, the modules are declared like this:

"active-modules": ["myInstance", "module2"],
"modules": {
	"myInstance": {
		"class-name": "path.to.module.ClassName",
		<MODULE SETTINGS>
	},
	"myInstance2": {
		"class-name": "path.to.module.ClassName",
		<MODULE SETTINGS>
	},
	"module2": {
		"class-name": "path.to.different.module.ClassName",
		<MODULE SETTINGS>
	}
}

The "modules" tag defines a list of modules associated with their instance name. The only obligatory tag to configure each module is the "class-name", indicating to the application which class to load. The <MODULE SETTINGS> depend on the type of the module, see below.

The "active-modules"-tag defines a list of those modules that should be loaded. The others will be ignored. That way, you can easily enable and disable whole modules as needed without changing their actual configuration.

Existing modules and how to configure them

ApplicationModule

This module provides the possibility to communicate directly with the application through commands:

"application-control": {
	"class-name": "de.piegames.voicepi.module.ApplicationModule",
	"exit-commands": [
		"EXIT", "QUIT", ...
	],
	"reload-commands": [
		"RELOAD", "REFRESH", ...
	]
}

It has only two functions, to reload all the modules or to stop the application. You can assign multiple commands to each of them

ActionModule

This is the only other module and the only one you will need in most of the cases. It will execute actions on specific commands. Before you start configuring it, you should get comfortable with configuring Actions.

"class-name": "de.piegames.voicepi.module.ActionModule",
"commands": {
	"COMMAND1": <ACTION>,
	"COMMAND2": <ACTION>,
	...
}

This way, you can add commands that do stuff and group them into different instances of this module. This will already handle many possible configurations you might want. But this module can be context specific too, which makes it really powerful. Add more tags, "commands-<STATE-NAME>" to create a new state and associate a list of commands to that state. The default "commands" tag is associated to the root state.

To use the newly defined states, you can specify the next state of a command by adding a "next-state": "<STATE-NAME>" to the configuration of its respective action. If this next state is not provided, it will default to going back to the root state after having executed that command. Here a minimal example for more see here:

"class-name": "de.piegames.voicepi.module.ActionModule",
"commands": {
	"MUSIC PLAYER": {
		<ACTION SETTINGS>
		"next-command": "music-player"
	}
},
"commands-music-player": {
	"PLAY": <ACTION>
	"RESUME": <ACTION>
}

How context sensitiveness works

The application has an internal state machine and a current state. Each commands defines the next state the machine will go into once executed. Only commands directly reachable from the current state can be executed. If a command points to a state with no other commands, the machine will go into the root state. The root state is the default and most important state, since it has most of the commands.

States are module-dependent. So, if you have two instances of a module with equal state names, they are not the same since they belong to a different module. Each module forms its own state sub-graph and the root state is the only state all modules have in common.

The commands of each state are unique. If a module registers an already existing command, the previous will be overridden with a warning. The order of the "activated-modules" is important. Due to states being linked to the module, those conflicts only can occur in the root state, not in the internal ones.

Developer documentation

TODO