Focus the eventbus docs a little more on built-in events.

I think thats what most people would use, with definitions of new
events being an advanced use.

Author: benclifford

docs/tildagon-apps/reference/eventbus.md

@@ -1,21 +1,31 @@
 # Eventbus overview
 
-You can register your events and event handlers with the [`Eventbus`](https://github.com/emfcamp/badge-2024-software/blob/main/modules/system/eventbus.py) package:
+The [`Eventbus`](https://github.com/emfcamp/badge-2024-software/blob/main/modules/system/eventbus.py) 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
 
-You can use your own events directly with an event handler that you register on the [`eventbus`](https://github.com/emfcamp/badge-2024-software/blob/main/modules/system/eventbus.py).
+Here are the basic steps for using the Eventbus. Often you won't need to do all of the steps, because some other piece of the software has already done it.
 
 1.  Import the `system.eventbus` package:
 
     ```python
     from system.eventbus import eventbus
     ```
 
-2.  Define an event:
+2.  Import an event definition, or define your own event type.
+
+    To use button events, for example:
+
+    ```python
+    from events.input import ButtonDownEvent
+    ```
+
+    To define your own event type, subclass ``Event``:
 
     ```python
-    class SpecialEvent:
+    from system.eventbus import Event
+
+    class SpecialEvent(Event):
     def __init__(self):
         pass
 
@@ -85,3 +95,43 @@ You can use the following methods on the `eventbus`:
 | `emit(event)` | Emit an event to the eventbus. The handler for the event must be synchronous. | `event` : The event, for example `ButtonDownEvent`. An `event` object must have the methods `__init__()` and `__str__()`. | None |
 | `emit_async(event)` | Emit an event to the eventbus. The handler for the event must be asynchronous. | `event` : The event, for example `ButtonDownEvent`. An `event` object must have the methods `__init__()` and `__str__()`. | None |
 | `remove(event_type, event_handler, app)` | Remove the event for an app from the eventbus. | <ul><li><code>event_type</code>: The event to be removed.</li><li><code>event_handler</code>: The asynchronous function to be called when the event fires to handle the event.</li><li><code>app</code>: The app this event is being removed for.</li></ul> | None |
+
+## 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](https://github.com/MatthewWilkes/md-updater/blob/main/sega.py) emits a button event when a user presses the equivalent buttons on an attached megadrive controller - so controller can be used to nagivate Tildagon apps.
+
+  ```python
+  from events.input import Button
+  ```
+
+* ``PatternDisable`` and ``PatternEnable``
+
+  When an app wants 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.
+
+  ```python
+  from system.patterndisplay.events import PatternDisable, PatternEnable
+  ```
+
+* ``HexpansionInsertionEvent`` and ``HexpansionRemovalEvent``
+
+  The hexpansion manager emits these events when it detects a hexpansion has been inserted or removed.
+
+  You can listen for these events if you want to do something interesting when a hexpansion is inserted or removed.
+
+  These events are only emitted for a PCB hexpansion with circuity on it, because it is the electrical connection that triggers these events. Purely-decorative (cardboard or 3-d printed) hexpansions won't cause these events to be emitted.
+
+  You probably shouldn't emit these events yourself.
+
+  ```python
+  from system.hexpansion.events import HexpansionInsertionEvent, HexpansionRemovalEvent
+  ```