Skip to content

Commit 81df66b

Browse files
docs: Add Linux dialout group to REPL page + minor improvements. (#747)
Updated a couple of links, and some minor formatting improvements.
1 parent fe0e8dd commit 81df66b

File tree

1 file changed

+38
-20
lines changed

1 file changed

+38
-20
lines changed

docs/devguide/repl.rst

Lines changed: 38 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,15 @@
44
Accessing the REPL
55
==================
66

7-
REPL (Read-Evaluate-Print-Loop) allows the micro:bit to read and evaluate code
7+
REPL (Read-Evaluate-Print-Loop) allows the micro:bit to read and evaluate code
88
in real-time as you write it.
99

10+
1011
Using the micro:bit Python Editor
1112
---------------------------------
13+
1214
The browser-based Python editor has built-in REPL support, that can be accessed
13-
using `WebUSB <https://developers.google.com/web/updates/2016/03/access-usb-devices-on-the-web>`_.
15+
using `WebUSB <https://web.dev/usb/>`_.
1416
You can read more about how WebUSB is used in the editors in this article on
1517
`direct flashing from the browser in the micro:bit apps and editors <https://support.microbit.org/support/solutions/articles/19000084059>`_.
1618

@@ -25,14 +27,16 @@ To use the REPL:
2527
3. Click the blue bar to ``Send CTRL-C for REPL`` or press ``CTRL`` + ``C`` on
2628
your keyboard to enter the REPL.
2729

30+
2831
Using a serial communication program
2932
------------------------------------
3033

31-
The `Mu Editor <https://codewith.mu/en/tutorials/1.0/repl>`_ has built-in
32-
support for REPL and even includes a real-time data plotter. Some other common
33-
options are `picocom` and `screen`. You will need to install a program and
34-
read the appropriate documentation to understand the basics of connecting to a
35-
device.
34+
The `Mu Editor <https://codewith.mu/en/tutorials/1.1/repl>`_ has built-in
35+
support for REPL and even includes a real-time data plotter.
36+
37+
Some other common options are `picocom` and `screen`. You will need to install
38+
a program and read the appropriate documentation to understand the basics of
39+
connecting to a device.
3640

3741

3842
Determining the port
@@ -43,34 +47,38 @@ Accessing the REPL on the micro:bit will require you to:
4347
* Determine the communication port identifier for the micro:bit
4448
* Use a program to establish communication with the device
4549

46-
The micro:bit will have a port identifier (tty, usb) that can be used by the
47-
computer for communicating. Before connecting to the micro:bit we must
50+
The micro:bit will have a port identifier (tty, usb) that can be used by the
51+
computer for communicating. Before connecting to the micro:bit we must
4852
determine the port identifier.
4953

50-
**Windows**
54+
Windows
55+
~~~~~~~
5156

5257
When you have installed the aforementioned drivers the micro:bit will appear in
5358
device-manager as a COM port.
5459

55-
**Mac OS**
60+
macOS
61+
~~~~~
5662

57-
Open Terminal and type ``ls /dev/cu.*`` to see a list of connected serial
58-
devices; one of them will look like ``/dev/cu.usbmodem1422`` (the exact number
63+
Open Terminal and type ``ls /dev/cu.*`` to see a list of connected serial
64+
devices; one of them will look like ``/dev/cu.usbmodem1422`` (the exact number
5965
will depend on your computer).
6066

61-
**Linux**
67+
Linux
68+
~~~~~
6269

63-
In terminal, type ``dmesg | tail`` which will show which ``/dev`` node the
70+
In terminal, type ``dmesg | tail`` which will show which ``/dev`` node the
6471
micro:bit was assigned (e.g. ``/dev/ttyUSB0``).
6572

6673

6774
Communicating with the micro:bit
6875
--------------------------------
6976

70-
Once you have found the port identifier you can use a serial terminal program
77+
Once you have found the port identifier you can use a serial terminal program
7178
to communicate with the micro:bit.
7279

73-
**Windows**
80+
Windows
81+
~~~~~~~
7482

7583
You may wish to use Tera Term, PuTTY, or another program.
7684

@@ -88,7 +96,8 @@ In PuTTY:
8896
* Select 'Serial' on the menu on the left, then click 'Open'
8997

9098

91-
**Mac OS**
99+
macOS
100+
~~~~~
92101

93102
Open Terminal and type ``screen /dev/cu.usbmodem1422 115200``, replacing
94103
``/dev/cu.usbmodem1422`` with the port you found earlier. This will open the
@@ -100,13 +109,22 @@ detach screen, but the serial port with still be locked, preventing other
100109
applications from accessing it. You can then restart screen by typing
101110
``screen -r``.
102111

112+
Linux
113+
~~~~~
114+
115+
To connect to Debian based distributions, like Ubuntu, you might need
116+
to add yourself to the ``dialout`` group, which grants write access to the
117+
serial device ``/dev/ttyACM0``::
118+
119+
sudo usermod -a -G dialout ${USER}
103120

104-
**Linux**
121+
You may need to relogin in order for the changes to groups to take effect.
105122

106123
Using the ``screen`` program, type ``screen /dev/ttyUSB0 115200``, replacing
107124
``/dev/ttyUSB0`` with the port you found earlier.
108125

109-
To exit, press Ctrl-A then \\ and answer Yes to the question. There are many
126+
To exit, press ``Ctrl-A`` then ``\`` and answer ``Yes`` to the question.
127+
There are many
110128
ways back to a command prompt including Ctrl-A then Ctrl-D, which will detach
111129
screen. All serial output from the micro:bit will still be received by
112130
``screen``, the serial port will be locked, preventing other applications from

0 commit comments

Comments
 (0)