Scripting API Reference

Quick reference for the openavc module available in all OpenAVC scripts.

For tutorials and patterns, see the Scripting Guide. This page is a lookup reference for every function, object, and property.

Import

from openavc import (
    on_event, on_state_change,               # Decorators
    devices, state, events, macros, log, isc, # Proxy objects
    delay, after, every, cancel_timer,        # Timer functions
    Event,                                    # Event class
)

You do not need to install anything. The openavc module is injected automatically by the Script Engine.

Decorators

@on_event(pattern)

@on_event("ui.press.btn_power")
async def handle(event):
    ...

Handler signatures:

async def handler(event) receives an Event object (recommended)
async def handler(event_name, payload) receives string + dict (legacy)

The engine detects the parameter count automatically.

@on_state_change(pattern)

@on_state_change("device.projector_main.power")
async def handle(key, old_value, new_value):
    ...

Handler signature: async def handler(key: str, old_value, new_value)

Event Object

Property / Method	Returns	Description
`event.name`	`str`	Full event name (e.g., `"ui.press.btn1"`)
`event.payload`	`dict`	Copy of the payload dictionary
`event.get(key, default)`	`Any`	Safe access to a payload field
`event.<key>`	`Any`	Attribute access to payload fields (raises `AttributeError` if missing)

devices

Control connected AV equipment.

Method	Returns	Description
`await devices.send(device_id, command, params=None)`	`Any`	Send a command to a device. `params` is a dict or `None`.
`devices.list()`	`list[dict]`	List all devices with connection status.

await devices.send("projector_main", "power_on")
await devices.send("projector_main", "set_input", {"input": "hdmi1"})
await devices.send("dsp1", "set_fader", {"channel": "program", "level": -12.0})
all_devices = devices.list()

Note: params must be a dict, not keyword arguments. Write {"input": "hdmi1"}, not input="hdmi1".

state

Read and write the reactive state store. All values are flat primitives (str, int, float, bool, None).

Method	Returns	Description
`state.get(key, default=None)`	`Any`	Read a state value.
`state.set(key, value, source="script")`	`None`	Write a state value. Triggers change notifications.
`state.delete(key)`	`None`	Remove a key entirely (unlike `set(key, None)` which keeps the key).
`state.get_namespace(prefix)`	`dict`	Read all keys under a prefix (e.g., `"device.projector_main."`).

State Key Namespaces

Prefix	Example	Who Writes
`device.<id>.*`	`device.projector_main.power`	Drivers (read-only for scripts)
`var.*`	`var.room_active`	Scripts, macros, UI
`ui.<id>.*`	`ui.btn_power.label`	Scripts (UI element overrides)
`system.*`	`system.uptime`	System (read-only)
`plugin.<id>.*`	`plugin.mqtt.connected`	Plugins
`isc.<peer_id>.*`	`isc.lobby.device.proj1.power`	ISC (remote state)

UI Element Overrides

Scripts can directly control UI element appearance by setting ui.* keys:

Key Pattern	Type	Description
`ui.<element_id>.label`	`str`	Override the element’s display text
`ui.<element_id>.bg_color`	`str`	Override background color (hex)
`ui.<element_id>.text_color`	`str`	Override text color (hex)
`ui.<element_id>.visible`	`bool`	Show or hide the element
`ui.<element_id>.opacity`	`float`	Set opacity (0.0 to 1.0)

Set a key to None to clear the override and revert to the feedback binding or default.

events

Emit custom events on the event bus.

Method	Returns	Description
`await events.emit(event_name, payload=None)`	`None`	Fire an event. `payload` is a dict or `None`.

await events.emit("custom.room_ready", {"zone": "auditorium"})

macros

Execute named macros.

Method	Returns	Description
`await macros.execute(macro_id)`	`None`	Run a macro by ID. The macro must exist in the project.

log

Write messages to the system log. Messages appear in the Programmer IDE Log View and script console.

Method	Description
`log.info(message)`	Informational message
`log.warning(message)`	Warning message
`log.error(message)`	Error message
`log.debug(message)`	Debug message (hidden unless debug level is enabled)

isc

Communicate with other OpenAVC instances on the network. ISC must be enabled in the project configuration.

Method	Returns	Description
`await isc.send_to(instance_id, event, payload=None)`	`None`	Send an event to a specific remote instance.
`await isc.broadcast(event, payload=None)`	`None`	Send an event to all connected instances.
`await isc.send_command(instance_id, device_id, command, params=None)`	`Any`	Send a device command to a remote instance’s equipment.
`isc.get_instances()`	`list[dict]`	List all discovered/connected peer instances.

Remote state from peers is available in the state store under isc.<peer_id>.<key>.

Timer Functions

delay(seconds)

Async sleep. Must be awaited. Pauses the current handler without blocking the system.

await delay(15)  # Wait 15 seconds

after(seconds, callback) -> str

Schedule a function to run once after a delay. Returns a timer ID for cancellation. Non-blocking.

timer_id = after(15, my_function)

every(seconds, callback) -> str

Schedule a function to run repeatedly at an interval. Returns a timer ID. Non-blocking.

timer_id = every(60, check_status)

cancel_timer(timer_id) -> bool

Cancel a timer created by after() or every(). Returns True if cancelled, False if not found.

cancelled = cancel_timer(timer_id)

Event Types

Events fired by the system that scripts can listen for with @on_event.

Pattern	Payload Fields	Description
`ui.press.<element_id>`	`element_id`	Button pressed
`ui.release.<element_id>`	`element_id`	Button released
`ui.hold.<element_id>`	`element_id`	Button held past threshold
`ui.change.<element_id>`	`element_id`, `value`	Slider or select value changed
`ui.submit.<element_id>`	`element_id`, `value`	Text input or keypad submitted
`ui.page.<page_id>`	`page_id`	Page navigation
`device.connected.<device_id>`	`device_id`	Device connected
`device.disconnected.<device_id>`	`device_id`	Device disconnected
`device.error.<device_id>`	`device_id`, `error`	Device communication error
`schedule.<schedule_id>`	`schedule_id`	Scheduled event fired
`macro.completed.<macro_id>`	`macro_id`	Macro finished executing
`system.started`	(none)	System startup complete
`system.stopping`	(none)	System shutting down
`isc.*.<event>`	`source_instance`, …	Event from a remote instance
`custom.<anything>`	(user-defined)	User-defined events