From 2e4274995dc54bd4c97f278fa808ef1f7abd8a28 Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Wed, 25 Mar 2020 12:57:50 +0100 Subject: [PATCH] doc/messaging: extend introduction. 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. --- doc/api/index.rst | 1 - doc/api/mailboxes.rst | 79 ------------------------------------------- doc/api/messaging.rst | 70 +++++++++++++++++++++++++++++++++----- 3 files changed, 62 insertions(+), 88 deletions(-) delete mode 100644 doc/api/mailboxes.rst diff --git a/doc/api/index.rst b/doc/api/index.rst index 42719a9..e54d050 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -39,5 +39,4 @@ Intro signaltypes motors - mailboxes .. frames diff --git a/doc/api/mailboxes.rst b/doc/api/mailboxes.rst deleted file mode 100644 index 24b71fc..0000000 --- a/doc/api/mailboxes.rst +++ /dev/null @@ -1,79 +0,0 @@ -Mailboxes -========= - -TODO: introduction... messages are sent immediately, received messages are held -in mailbox for getting later. - -.. rubric:: Pairing - -Before two EV3s can communicate with each other via Bluetooth, they must be -paired. - -TODO: screenshots of pairing with brickman, don't press the connect button! - - -.. rubric:: Client and server - -Programs can be written using either an EV3 mailbox *client* object or an EV3 -mailbox *server* object. - -The only difference between the *client* and the *server* is which one -initiates the connection at the beginning of the program. After that, sending -and receiving messages is bidirectional and works the same from either point of -view. - -The *server* waits for an incoming connection while the *client* initiates the -connection. Therefore, the server program must always be started first. If not, -both programs will wait forever for a connection. - - -Here is a basic example where two EV3s are connected and send greetings to -each other. - -.. rubric:: Client program - -.. literalinclude:: - ../../pybricks-projects/snippets/ev3/bluetooth_client/client.py - -.. rubric:: Server program - -.. literalinclude:: - ../../pybricks-projects/snippets/ev3/bluetooth_server/server.py - - -.. rubric:: EV3-G compatibility - -TODO: screenshots of EV3-G programs, difference between client and server -program is that client program has connect block. Server is always running. - -TODO: show equivalent blocks - -- :class:`pybricks.messaging.LogicMailbox` -- :class:`pybricks.messaging.NumericMailbox` -- :class:`pybricks.messaging.TextMailbox` - - -.. rubric:: More than two bricks - -A single client EV3 can connect to multiple server EV3s or a single server EV3 -can accept connections from multiple clients. - -TODO: the actual implementation needs to be updated to match this example. - -Example:: - - client = EV3MailboxClient() - - # connect to 4 different servers - client.connect(SERVER1) - client.connect(SERVER2) - client.connect(SERVER3) - client.connect(SERVER4) - - -Example:: - - server = EV3MailboxServer() - - # wait for 4 clients to connect - server.wait_for_connection(4) diff --git a/doc/api/messaging.rst b/doc/api/messaging.rst index 0b49627..89e1ed2 100644 --- a/doc/api/messaging.rst +++ b/doc/api/messaging.rst @@ -1,12 +1,28 @@ :mod:`messaging ` -- Messaging ================================================== -.. automodule:: pybricks.messaging - :no-members: +.. module:: pybricks.messaging .. currentmodule:: pybricks.messaging -Introductory text. An example network is shown in :numref:`fig_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: @@ -17,9 +33,35 @@ Introductory text. An example network is shown in :numref:`fig_messaging`. An example network with one server and one clients. +.. toggle-header:: + :header: **Show/hide full server example** -Connections ------------- + **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 @@ -29,7 +71,15 @@ Connections Mailboxes --------- -Mailboxes are used to send data to and from other EV3s. +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 @@ -42,8 +92,12 @@ Mailboxes are used to send data to and from other EV3s. .. autoclass:: TextMailbox :no-members: -Bigger networks ----------------- +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: