mirror of
https://github.com/pybricks/pybricks-api.git
synced 2026-09-12 01:24:17 +00:00
Laurens Valk
2e4274995d
Also drop separate, nearly empty Mailboxes page. Ultimately we may separate this page into two pieces again, but for now a single concise page is clearer than two incomplete pages.
110 lines
3.1 KiB
ReStructuredText
110 lines
3.1 KiB
ReStructuredText
:mod:`messaging <pybricks.messaging>` -- Messaging
|
|
==================================================
|
|
|
|
.. module:: pybricks.messaging
|
|
|
|
.. currentmodule:: pybricks.messaging
|
|
|
|
An EV3 Brick can send information to another EV3 Brick using Bluetooth. This
|
|
page shows you how to connect multiple bricks and how to write scripts to send
|
|
messages between them.
|
|
|
|
Pairing EV3 Bricks
|
|
------------------
|
|
|
|
.. todo::
|
|
|
|
Brief intro and screenshots of pairing with brickman.
|
|
|
|
Server and Client
|
|
-----------------
|
|
|
|
A wireless network consists of EV3 Bricks acting as servers or clients. A
|
|
example with one server and one client is shown in :numref:`fig_messaging`.
|
|
Messages can be sent in both ways: the server can send a message to the client,
|
|
and the client can send a message to the server.
|
|
|
|
.. _fig_messaging:
|
|
|
|
.. figure:: ../api/images/messaging_label.png
|
|
:width: 90 %
|
|
:alt: messaging
|
|
:align: center
|
|
|
|
An example network with one server and one clients.
|
|
|
|
.. toggle-header::
|
|
:header: **Show/hide full server example**
|
|
|
|
**Example: EV3 Bluetooth Server.**
|
|
|
|
This is the full version of the excerpt shown in :numref:`fig_messaging`.
|
|
|
|
.. literalinclude:: ../../pybricks-projects/snippets/ev3/bluetooth_server/server.py
|
|
|
|
.. toggle-header::
|
|
:header: **Show/hide full client example**
|
|
|
|
**Example: EV3 Bluetooth Client.**
|
|
|
|
This is the full version of the excerpt shown in :numref:`fig_messaging`.
|
|
|
|
.. literalinclude:: ../../pybricks-projects/snippets/ev3/bluetooth_client/client.py
|
|
|
|
|
|
The only difference between the client and the server is which one initiates
|
|
the connection at the beginning of the program:
|
|
|
|
- The **server** must always be started first. It uses the
|
|
``BluetoothMailboxServer`` class. Then it waits for clients using
|
|
the ``wait_for_connection`` method.
|
|
- The **client** uses the ``BluetoothMailboxClient`` class. It
|
|
connects to the server using the ``connect`` method.
|
|
- After that, sending and receiving messages is done in the same way on
|
|
both EV3 Bricks.
|
|
|
|
.. autoclass:: BluetoothMailboxServer
|
|
|
|
.. autoclass:: BluetoothMailboxClient
|
|
|
|
|
|
Mailboxes
|
|
---------
|
|
|
|
Mailboxes are used to send data to and from other EV3 Bricks.
|
|
|
|
A Mailbox has a ``name``, similar to the "subject" of an email. If two EV3
|
|
Bricks have a Mailbox with the same name, they can send messages between them.
|
|
Each EV3 Brick can read its own Mailbox, and send messages to the Mailbox on
|
|
the other EV3 Brick.
|
|
|
|
Depending on the type of messages you would like to exchange (bytes, booleans,
|
|
numbers, or text), you can choose one of the Mailboxes below.
|
|
|
|
.. autoclass:: Mailbox
|
|
|
|
.. autoclass:: LogicMailbox
|
|
:no-members:
|
|
|
|
.. autoclass:: NumericMailbox
|
|
:no-members:
|
|
|
|
.. autoclass:: TextMailbox
|
|
:no-members:
|
|
|
|
Making bigger networks
|
|
----------------------
|
|
|
|
The classes in this module are not limited to just two EV3 Bricks. for
|
|
example, you can add more clients to your network. An example with pseudo-code
|
|
is shown in :numref:`fig_messaging_network`.
|
|
|
|
.. _fig_messaging_network:
|
|
|
|
.. figure:: ../api/images/messaging_network_label.png
|
|
:width: 90 %
|
|
:alt: messaging
|
|
:align: center
|
|
|
|
An example network with one server and two clients.
|