ez.bus - ezOS Lua API

audio bus crypto display ez global gps keyboard mesh net radio sprite storage synth system wifi

Publish/subscribe message bus for decoupled communication

Enables loose coupling between components through topic-based messaging. Any component can post messages to topics, and any component can subscribe to receive them. Messages are delivered synchronously during the next scheduler update. See the Message Bus tab for available system topics.

Functions

has_subscribers() → boolean Check if a topic has any active subscribers

ez.bus.has_subscribers(topic) -> boolean

Useful for avoiding expensive work when no one is listening. For example, skip serializing debug data if no debug panel is subscribed.

Parameter	Description
topic	Topic string to check

Returns: true if one or more subscribers exist

if ez.bus.has_subscribers("debug/memory") then
ez.bus.post("debug/memory", {heap = ez.system.get_free_heap()})
end

pending_count() → integer Get number of messages waiting in queue

ez.bus.pending_count() -> integer

Returns the number of messages posted but not yet delivered to subscribers. Messages are delivered during the main loop, so this count is typically 0 or low. A high count might indicate subscribers are slow.

Returns: Number of pending messages

local pending = ez.bus.pending_count()
if pending > 10 then
print("Warning: message queue backing up")
end

post() Post a message to a topic

ez.bus.post(topic, data)

Sends a message to all subscribers of the given topic. The data can be a string or a table. Messages are queued and delivered on the next main loop iteration, so posting is non-blocking. Use consistent topic naming like "module/event" (e.g., "screen/pushed", "mesh/node_discovered").

Parameter	Description
topic	Topic string to post to
data	Message data (string or table)

-- Post a string message
ez.bus.post("status/update", "connected")
-- Post a table with structured data
ez.bus.post("chat/message", {sender = "Alice", text = "Hello!"})

subscribe() → subscription_id Subscribe to a topic with a callback function

ez.bus.subscribe(topic, callback) -> subscription_id

The message bus provides pub/sub communication between Lua scripts and C++ code. Topics are strings like "screen/pushed" or "mesh/message". When a message is posted to a topic, all subscribers receive it with the topic name and data payload. Keep the returned subscription ID to unsubscribe later.

Parameter	Description
topic	Topic string to subscribe to
callback	Function(topic, data) called when message received

Returns: Subscription ID for use with unsubscribe

local sub_id = ez.bus.subscribe("mesh/message", function(topic, data)
print("Received:", data.text, "from", data.sender)
end)

unsubscribe() → boolean Unsubscribe from a topic

ez.bus.unsubscribe(subscription_id) -> boolean

Removes a subscription created with subscribe(). Always unsubscribe when a screen exits or a service shuts down to prevent memory leaks and stale callbacks. Returns false if the subscription ID was not found.

Parameter	Description
subscription_id	ID returned from subscribe()

Returns: true if subscription was found and removed

function MyScreen:on_exit()
if self.sub_id then
ez.bus.unsubscribe(self.sub_id)
end
end