Ga naar inhoud

events

EventService #

Met behulp van deze klasse kan je luisteren naar gebeurtenissen (events) die plaatsvinden op de micro:bit. De micro:bit meldt deze gebeurtenissen op zijn interne messagebus.

De device ids en event ids verschillen tussen de verschillende micro:bit versies. Zie kaspersmicrobit.services.v1_events voor de ids van de micro:bit v1, en kaspersmicrobit.services.v2_events voor de ids van de micro:bit v2

Ook de micro:bit zelf kan via deze service aangeven dat hij geïnteresseerd is om bepaalde events te onvangen. Je kan dus ook zelfgemaakte events naar de micro:bit doorsturen.

Dit zijn alle mogelijkheden aangeboden door de bluetooth event service

Zie ook: 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

Kijkt na of de event bluetooth service gevonden wordt op de geconnecteerde micro:bit.

Returns:

  • bool –

    true als de event service gevonden werd, false indien niet.

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]
)

Deze methode kan je oproepen wanneer je verwittigd wil worden welke events de micro:bit zou willen ontvangen Wanneer een event een event_waarde van 0 bevat betekent dit dat de micro:bit geinformeerd wil worden van elke event van het gegeven device_id

Je kan dan met write_client_event de micro:bit op de hoogte houden van deze gebeurtenissen

Parameters:

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

    een functie die wordt opgeroepen met een Event

Raises:

  • BluetoothServiceNotFound –

    Wanneer de events service niet actief is op de micro:bit

  • BluetoothCharacteristicNotFound –

    Wanneer de events service actief is, maar er geen manier was om de notificaties voor de microbit requirements te activeren (komt normaal gezien niet voor)

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]

Leest de lijst van events die de micro:bit zou willen ontvangen van jou wanneer ze zich voordoen Wanneer een event een event_waarde van 0 bevat betekent dit dat de micro:bit geinformeerd wil worden van elke event van het gegeven device_id

Je kan dan met write_client_event de micro:bit op de hoogte houden van deze gebeurtenissen

Returns:

  • List[Event] –

    List[Event]: Een lijst van events waarvan je de micro:bit moet verwittigen wanneer ze zich voordoen

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])

Deze methode kan je oproepen wanneer je verwittigd wil worden van events die zich voordoen op de micro:bit Je zal enkel verwittigd worden van events waarvan je met write_client_requirements hebt aangegeven dat je ze wil ontvangen

Parameters:

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

    een functie die wordt opgeroepen met een 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]

Leest de lijst van events die zich hebben voorgedaan op de micro:bit Je zal enkel events kunnen uitlezen waarvan je met write_client_requirements hebt aangegeven dat je ze wil ontvangen

Returns:

  • List[Event] –

    List[Event]: Een lijst van events die zich hebben voorgedaan op de 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)

Met deze methode geeft je aan in welke events van de micro:bit je geïnteresseerd bent. Deze events kan je dan ontvangen met notify_microbit_event of uitlezen met read_microbit_event als ze zich voordoen.

Wanneer je een event met een event_waarde van 0 schrijft betekent dit dat je geinformeerd wil worden van elke event van het gegeven device_id

Parameters:

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

    de events die je wil ontvangen van de 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)

Met deze methode zend je events naar de micro:bit. Hiermee kan je de micro:bit op de hoogte houden van events die zich voordoen in je applicatie. Zend enkel events waarvan de micro:bit heeft aangegeven ze te willen ontvangen door notify_microbit_requirements of read_microbit_requirements

Parameters:

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

    de events die je wil verzenden naar de 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())