Eventbus overview

The Eventbus lets a Tildagon app broadcast an event, and other apps register to receive that event if they are interested. Some examples are: a button press (a ButtonDownEvent) or an app wants to take over the pattern LEDs (a PatternDisable event). You can also define your own types of event, if you have something interesting to broadcast to other apps.

Usage

The following steps are the basic steps for using the Eventbus directly with an event handler that you register on the eventbus.

1. Import the system.eventbus and events packages:

   from system.eventbus import eventbus
   from events import Event
   

2. Import an event definition, or define your own event type.

   To use button events, for example:

   from events.input import ButtonDownEvent
   

   To define your own event type, subclass Event:

   from system.eventbus import Event
   
   class SpecialEvent(Event):
   def __init__(self):
       pass
   
       def __str__(self):
           return "special event"
   

3. Define a synchronous or asynchronous method to be called when the event occurs:

   def handle_event(self, event):
       # do something
   

   async def handle_event_async(self, event):
       # do something
   

4. Register your event handler, for example in the __init__ method of your app with the event and the event handler. Depending on whether the event handler is a synchronous or asynchronous method call on() or on_async():

   def __init__(self):
       eventbus.on(SpecialEvent, self.handle_event, self.app)
   

   def __init__(self):
       eventbus.on_async(SpecialEvent, self.handle_event_async, self.app)
   

5. Add code to emit the event, for example in your app's update() method. Depending on whether you are emitting in a synchronous or asynchronous method, call emit() or emit_async():

   def update(self, delta):
       # If something happens
       eventbus.emit(SpecialEvent())
   

   async def update(self, delta):
       # If something happens
       await eventbus.emit_async(SpecialEvent())
   

6. Remove the event handler when the app is minimised or closed.

   eventbus.remove(SpecialEvent, self.handle_event, self.app)
   

   Warning

   Make sure you remove the event handler when the app is minimised or closed!

You can see a more comprehensive example in dialog.py or pingpong_app.py.

Methods

You can use the following methods on the eventbus:

Common built-in events

There are a lot of event types built into the firmware. Here are a few that are useful to know about:

• ButtonDownEvent and ButtonUpEvent

This is sent by the firmware when one of the buttons is pressed.

You can register to receive this event if you want to respond to button presses in your application.

If you want to make the Tildagon think a button has been pressed, you can emit this event. For example, the megadrive controller hexpansion firmware emits a button event when a user presses the equivalent buttons on an attached megadrive controller so the controller can be used to navigate Tildagon apps.

from events.input import Button

• PatternDisable and PatternEnable

When an app is supposed to take over the front LEDs that usually show a pattern, it can emit a PatternDisable event. The pattern manager will receive that event and stop updating the LEDs, leaving them free for the app. Then the app can set the LEDs however it wants. When the app is finished with the LEDs (for example, when it is put in the background) it can emit a PatternEnable event to start the pattern again.

You probably don't need to listen for this event.

from system.patterndisplay.events import PatternDisable, PatternEnable

• HexpansionMountedEvent and HexpansionUnmountedEvent

The hexpansion manager emits these events after the firmware has finished handling the hexpansion being inserted or removed. For example, after the EEPROM filesystem has been mounted and a contained hexpansion app has been started.

In most cases you should listen for these events rather than HexpansionInsertionEvent and HexpansionRemovalEvent, because by the time HexpansionMountedEvent fires the hexpansion is fully ready to use.

from system.hexpansion.events import HexpansionMountedEvent, HexpansionUnmountedEvent

• HexpansionInsertionEvent and HexpansionRemovalEvent

The hexpansion manager emits these events immediately when it detects a hexpansion being inserted or removed. They fire before the firmware has finished its own internal handling (such as mounting the EEPROM filesystem).

These events are only emitted for a PCB hexpansion with circuitry on it, because it is the electrical connection that triggers these events. Purely-decorative (cardboard or 3D printed) hexpansions do not cause these events to be emitted.

You probably shouldn't emit these events yourself.

from system.hexpansion.events import HexpansionInsertionEvent, HexpansionRemovalEvent

• EmotePositiveEvent and EmoteNegativeEvent

Emote events are a lightweight way for a foreground app to signal to other components, such as hexpansion drivers or the back-of-board LED manager, that something good or bad just happened in the user interface. The components can react in their own way, for example by flashing the back LEDs green or red, or playing a short jingle on an audio hexpansion.

By default the firmware flashes the backboard LEDs green on a positive emote and red on a negative emote. This behaviour can be turned off in the badge settings.

Guidelines for use:

• Only emit emotes when your app is in the foreground.
• Send at most a handful of emotes per minute, as receivers may generate behaviours lasting several seconds (e.g. an audio jingle).

from events.emote import EmotePositiveEvent, EmoteNegativeEvent

# signal success
eventbus.emit(EmotePositiveEvent())

# signal failure
eventbus.emit(EmoteNegativeEvent())

If you are writing a hexpansion driver or app, you can listen for emote events:

from events.emote import EmotePositiveEvent, EmoteNegativeEvent

eventbus.on(EmotePositiveEvent, self.handle_positive, self)
eventbus.on(EmoteNegativeEvent, self.handle_negative, self)