Skip to content

events

EventService #

Using this class you can listen to events that take place on the micro:bit. The micro:bit reports these events on its internal message bus.

The device IDs and event IDs differ between the different micro:bit versions. See kaspersmicrobit.services.v1_events for the ids of the micro:bit v1, and kaspersmicrobit.services.v2_events for the ids of the micro:bit v2

The micro:bit itself can also indicate through this service that it is interested in receiving certain events. So you can also forward self-made events to the micro:bit.

These are all options offered by the Bluetooth event service

See Also: https://lancaster-university.github.io/microbit-docs/ble/event-service/

Source code in src/kaspersmicrobit/services/events.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
class EventService:
    """
    Using this class you can listen to events that take place on the micro:bit.
    The micro:bit reports these events on its internal message bus.

    The device IDs and event IDs differ between the different micro:bit versions.
    See `kaspersmicrobit.services.v1_events` for the ids of the micro:bit v1, and
    `kaspersmicrobit.services.v2_events` for the ids of the micro:bit v2

    The micro:bit itself can also indicate through this service that it is interested in receiving certain events.
    So you can also forward self-made events to the micro:bit.

    These are all options offered by the Bluetooth event service

    See Also: https://lancaster-university.github.io/microbit-docs/ble/event-service/
    """

    def __init__(self, device: BluetoothDevice):
        self._device = device

    def is_available(self) -> bool:
        """
        Checks whether the event Bluetooth service is found on the connected micro:bit.

        Returns:
            true if the event service was found, false if not.
        """
        return self._device.is_service_available(Service.EVENT)

    def notify_microbit_requirements(self, callback: Callable[[Event], None]):
        """
        You can call this method when you want to be notified which events the micro:bit would like to receive
        When an event contains an event_value of 0, this means that the micro:bit wants to be informed of each
        event of the given device_id

        You can then use `write_client_event` to keep the micro:bit informed of these events

        Args:
            callback: a function that is called with an Event

        Raises:
            errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
                to activate the notifications for the microbit requirements (normally does not occur)
        """
        self._device.notify(Characteristic.MICROBIT_REQUIREMENTS,
                            lambda sender, data: _for_each(Event.list_from_bytes(data), callback))

    def read_microbit_requirements(self) -> List[Event]:
        """
        Reads the list of events that the micro:bit would like to receive from you as they occur
        When an event contains an event_value of 0, this means that the micro:bit wants to be informed of each
        event of the given device_id

        You can then use `write_client_event` to keep the micro:bit informed of these events

        Returns:
            List[Event]: A list of events that you need to notify the micro:bit when they occur

        Raises:
            errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
                to read the microbit requirements (normally does not occur)
        """
        return Event.list_from_bytes(self._device.read(Service.EVENT, Characteristic.MICROBIT_REQUIREMENTS))

    def notify_microbit_event(self, callback: Callable[[Event], None]):
        """
        You can call this method when you want to be notified of events that occur on the micro:bit
        You will only be notified of events that you have indicated with `write_client_requirements`
        you want to receive them

        Args:
            callback: a function that is called with an Event

        Raises:
            errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
                to activate the notifications for the microbit events (normally does not occur)
        """
        self._device.notify(Service.EVENT, Characteristic.MICROBIT_EVENT,
                            lambda sender, data: _for_each(Event.list_from_bytes(data), callback))

    def read_microbit_event(self) -> List[Event]:
        """
        Reads the list of events that occurred on the micro:bit
        You will only be able to read events for which you have specified with `write_client_requirements`
        you want to receive them

        Returns:
            List[Event]: A list of events that occurred on the micro:bit

        Raises:
            errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
                to read the microbit events (normally does not occur)
        """
        return Event.list_from_bytes(self._device.read(Service.EVENT, Characteristic.MICROBIT_EVENT))

    def write_client_requirements(self, *events: Event):
        """
        Using this method you indicate which micro:bit events you are interested in. Then, you'll be able to receive these events
        with `notify_microbit_event` or read out with `read_microbit_event` when they occur.

        When you write an event with an event_value of 0, this means that you want to be informed of each
        event of the given device_id

        Args:
            *events (Event): the events you want to receive from the micro:bit

        Raises:
            errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
                to write the client requirements (normally does not occur)
        """
        for event in events:
            self._device.write(Service.EVENT, Characteristic.CLIENT_REQUIREMENTS, event.to_bytes())

    def write_client_event(self, *events: Event):
        """
        With this method you send events to the micro:bit. This allows you to keep the micro:bit informed of events that
        occur in your application. Only send events that the micro:bit has indicated it wants to receive
        by `notify_microbit_requirements` or `read_microbit_requirements`

        Args:
           *events (Event): the events you want to send to the micro:bit

        Raises:
            errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
            errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
                to write the client events (normally does not occur)
        """
        for event in events:
            self._device.write(Service.EVENT, Characteristic.CLIENT_EVENT, event.to_bytes())

is_available #

is_available() -> bool

Checks whether the event Bluetooth service is found on the connected micro:bit.

Returns:

  • bool –

    true if the event service was found, false if not.

Source code in src/kaspersmicrobit/services/events.py 
38
39
40
41
42
43
44
45
def is_available(self) -> bool:
    """
    Checks whether the event Bluetooth service is found on the connected micro:bit.

    Returns:
        true if the event service was found, false if not.
    """
    return self._device.is_service_available(Service.EVENT)

notify_microbit_requirements #

notify_microbit_requirements(
    callback: Callable[[Event], None]
)

You can call this method when you want to be notified which events the micro:bit would like to receive When an event contains an event_value of 0, this means that the micro:bit wants to be informed of each event of the given device_id

You can then use write_client_event to keep the micro:bit informed of these events

Parameters:

  • callback (Callable[[Event], None]) –

    a function that is called with an Event

Raises:

Source code in src/kaspersmicrobit/services/events.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def notify_microbit_requirements(self, callback: Callable[[Event], None]):
    """
    You can call this method when you want to be notified which events the micro:bit would like to receive
    When an event contains an event_value of 0, this means that the micro:bit wants to be informed of each
    event of the given device_id

    You can then use `write_client_event` to keep the micro:bit informed of these events

    Args:
        callback: a function that is called with an Event

    Raises:
        errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
            to activate the notifications for the microbit requirements (normally does not occur)
    """
    self._device.notify(Characteristic.MICROBIT_REQUIREMENTS,
                        lambda sender, data: _for_each(Event.list_from_bytes(data), callback))

read_microbit_requirements #

read_microbit_requirements() -> List[Event]

Reads the list of events that the micro:bit would like to receive from you as they occur When an event contains an event_value of 0, this means that the micro:bit wants to be informed of each event of the given device_id

You can then use write_client_event to keep the micro:bit informed of these events

Returns:

  • List[Event] –

    List[Event]: A list of events that you need to notify the micro:bit when they occur

Raises:

Source code in src/kaspersmicrobit/services/events.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def read_microbit_requirements(self) -> List[Event]:
    """
    Reads the list of events that the micro:bit would like to receive from you as they occur
    When an event contains an event_value of 0, this means that the micro:bit wants to be informed of each
    event of the given device_id

    You can then use `write_client_event` to keep the micro:bit informed of these events

    Returns:
        List[Event]: A list of events that you need to notify the micro:bit when they occur

    Raises:
        errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
            to read the microbit requirements (normally does not occur)
    """
    return Event.list_from_bytes(self._device.read(Service.EVENT, Characteristic.MICROBIT_REQUIREMENTS))

notify_microbit_event #

notify_microbit_event(callback: Callable[[Event], None])

You can call this method when you want to be notified of events that occur on the micro:bit You will only be notified of events that you have indicated with write_client_requirements you want to receive them

Parameters:

  • callback (Callable[[Event], None]) –

    a function that is called with an Event

Raises:

Source code in src/kaspersmicrobit/services/events.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def notify_microbit_event(self, callback: Callable[[Event], None]):
    """
    You can call this method when you want to be notified of events that occur on the micro:bit
    You will only be notified of events that you have indicated with `write_client_requirements`
    you want to receive them

    Args:
        callback: a function that is called with an Event

    Raises:
        errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
            to activate the notifications for the microbit events (normally does not occur)
    """
    self._device.notify(Service.EVENT, Characteristic.MICROBIT_EVENT,
                        lambda sender, data: _for_each(Event.list_from_bytes(data), callback))

read_microbit_event #

read_microbit_event() -> List[Event]

Reads the list of events that occurred on the micro:bit You will only be able to read events for which you have specified with write_client_requirements you want to receive them

Returns:

  • List[Event] –

    List[Event]: A list of events that occurred on the micro:bit

Raises:

Source code in src/kaspersmicrobit/services/events.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def read_microbit_event(self) -> List[Event]:
    """
    Reads the list of events that occurred on the micro:bit
    You will only be able to read events for which you have specified with `write_client_requirements`
    you want to receive them

    Returns:
        List[Event]: A list of events that occurred on the micro:bit

    Raises:
        errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
            to read the microbit events (normally does not occur)
    """
    return Event.list_from_bytes(self._device.read(Service.EVENT, Characteristic.MICROBIT_EVENT))

write_client_requirements #

write_client_requirements(*events: Event)

Using this method you indicate which micro:bit events you are interested in. Then, you'll be able to receive these events with notify_microbit_event or read out with read_microbit_event when they occur.

When you write an event with an event_value of 0, this means that you want to be informed of each event of the given device_id

Parameters:

  • *events (Event, default: () ) –

    the events you want to receive from the micro:bit

Raises:

Source code in src/kaspersmicrobit/services/events.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def write_client_requirements(self, *events: Event):
    """
    Using this method you indicate which micro:bit events you are interested in. Then, you'll be able to receive these events
    with `notify_microbit_event` or read out with `read_microbit_event` when they occur.

    When you write an event with an event_value of 0, this means that you want to be informed of each
    event of the given device_id

    Args:
        *events (Event): the events you want to receive from the micro:bit

    Raises:
        errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
            to write the client requirements (normally does not occur)
    """
    for event in events:
        self._device.write(Service.EVENT, Characteristic.CLIENT_REQUIREMENTS, event.to_bytes())

write_client_event #

write_client_event(*events: Event)

With this method you send events to the micro:bit. This allows you to keep the micro:bit informed of events that occur in your application. Only send events that the micro:bit has indicated it wants to receive by notify_microbit_requirements or read_microbit_requirements

Parameters:

  • *events (Event, default: () ) –

    the events you want to send to the micro:bit

Raises:

Source code in src/kaspersmicrobit/services/events.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def write_client_event(self, *events: Event):
    """
    With this method you send events to the micro:bit. This allows you to keep the micro:bit informed of events that
    occur in your application. Only send events that the micro:bit has indicated it wants to receive
    by `notify_microbit_requirements` or `read_microbit_requirements`

    Args:
       *events (Event): the events you want to send to the micro:bit

    Raises:
        errors.BluetoothServiceNotFound: When the events service is not active on the micro:bit
        errors.BluetoothCharacteristicNotFound: When the events service is running but there was no way
            to write the client events (normally does not occur)
    """
    for event in events:
        self._device.write(Service.EVENT, Characteristic.CLIENT_EVENT, event.to_bytes())