macro module

Description

Macros allow to script simple tasks like turning motors simultaneously or drive them to certain positions, handling everything on the hardware level. Combined with the command structure of the modules this already allows extensive customization without changes to the codebase (automatization tutorial coming soon).

States

Every state is a collection of commands, instructions to other (or even this) module. A state is identified and referred to by a string. Once activated, all commands are executed in the order they are entered.

State Settings

setting	type	default	range	description
controlKey	String	"state"	–	name of the state; used to both call the state in commands and refer to it in status
infoLED	String	""	–	ID of an LED, module will instruct LED to display if changes are made to the module by a user

Commands

A command is one single, specific instruction to a module. The possible keys for the modules can be found on the pages of the individual modules.

Command Settings

setting	type	range	description
controlId	String	–	ID of the module to receive the command
controlKey	String	–	key tha identifies the command action
controlVal	boolean integer float String	–	value assigned to the key[1]

1. ↑may vary depending on the key. See the specific key of the addressed module to find the permitted types.

Settings

setting	type	range	description
controlKey	String	–	key to be used instead of xxxx in the command status events to represent states[2]
initState	String	–	specifies the state the module will be in after initialization[3]

2. ↑The controlKey can be freely chosen and might be anything like state, position, cartridge -- whatever describes it best.
3. ↑it is assumed that all necessary initialization is taken care of by the individual modules -- this is the resulting state of initialization. No commands will be sent on initialization. If you want a different state after the initialization is finished, use a separate state and activate it via custom event hooks.

Command Keys

key	type	range	description
getStatus	boolean	–	send status if true
xxxx	String	–	activate the specified state
wait	integer	≥ -1	wait for the specified time (in ms) before resuming to execute commands; -1 means stop waiting; 0 means waiting indefinetly
listen	String	–	set a controlId to listen for, interrupting a wait when the specified module signals ready[4]
complete[5]	integer	≥ 0	wait for the ready[4] signal of the last controlId or for the specified timeout (in ms), whatever occurs first; 0 means waiting indefinitely

4. ↑while the module is waiting, it will listen for both internal ready events or status events containing the field "busy":false. If one of these occur, it will resume normal operation. As a result the controlId that is waited for does not need to be located on the same hardware, but needs to emit a status containing the busy field in case it is not (i.e. output, servo motor, stepper motor, macro).
5. ↑this command should only be used from the module itself, calling it from outside will lead to undefined behavior. Essentially a shorthand for the combination of "listen":lastId with "wait":duration -- currently the only method that determines lastId automatically.

Status

"controlId":"experimentSelection",
"status":
{
    "busy":false,
    "state":"pinhole"
}

• busy – boolean, indicates that the module is currently in the process of activating a state when true
• xxxx – String, identifier of the current state^[6]

6. ↑ reads aborted if the state execution was stopped before completion

Events

• busy – occurs when a state is activating and the module is currently in the process of executing commands or waiting for a timed condition
• ready – occurs when a state has been successfully executed and the module is waiting for further commands