Skip to content

Commit dc4c8f5

Browse files
bennuttallbennuttall
committed
Split Pi Zero OTG docs into new page
1 parent 471e80f commit dc4c8f5

File tree

3 files changed

+143
-133
lines changed

3 files changed

+143
-133
lines changed

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ Table of Contents
1212
recipes_advanced
1313
remote_gpio
1414
recipes_remote_gpio
15+
pi_zero_otg
1516
source_values
1617
cli_tools
1718
faq
@@ -36,4 +37,3 @@ Indices and tables
3637
* :ref:`genindex`
3738
* :ref:`modindex`
3839
* :ref:`search`
39-

‎docs/pi_zero_otg.rst‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
===============
2+
Pi Zero USB OTG
3+
===============
4+
5+
The `Raspberry Pi Zero`_ and `Pi Zero W`_ feature a USB OTG port, allowing users
6+
to configure the device as (amongst other things) an Ethernet device. In this
7+
mode, it is possible to control the Pi Zero's GPIO pins over USB from another
8+
computer using the :doc:`remote_gpio` feature.
9+
10+
GPIO expander method - no SD card required
11+
==========================================
12+
13+
The GPIO expander method allows you to boot the Pi Zero over USB from the PC,
14+
without an SD card. Your PC sends the required boot firmware to the Pi over the
15+
USB cable, launching a mini version of Raspbian and booting it in RAM. The OS
16+
then starts the pigpio daemon, allowing "remote" access over the USB cable.
17+
18+
At the time of writing, this is only possible using either the Raspberry Pi
19+
Desktop x86 OS, or Ubuntu (or a derivative), or from another Raspberry Pi. Usage
20+
from Windows and Mac OS is not supported at present.
21+
22+
Raspberry Pi Desktop x86 setup
23+
------------------------------
24+
25+
1. Download an ISO of the Raspberry Pi Desktop OS from raspberrypi.org (this
26+
must be the Stretch release, not the older Jessie image).
27+
28+
2. Write the image to a USB stick or burn to a DVD.
29+
30+
3. Live boot your PC or Mac into the OS (select "Run with persistence" and your
31+
computer will be back to normal afterwards).
32+
33+
Raspberry Pi (Raspbian) setup
34+
-----------------------------
35+
36+
1. Update your package list and install the ``usbbootgui`` package:
37+
38+
.. code-block:: console
39+
40+
$ sudo apt update
41+
$ sudo apt install usbbootgui
42+
43+
Ubuntu setup
44+
------------
45+
46+
1. Add the Raspberry Pi PPA to your system:
47+
48+
.. code-block:: console
49+
50+
$ sudo add-apt-repository ppa:rpi-distro/ppa
51+
52+
2. If you have previously installed ``gpiozero`` or ``pigpio`` with pip,
53+
uninstall these first:
54+
55+
.. code-block:: console
56+
57+
$ sudo pip3 uninstall gpiozero pigpio
58+
59+
3. Install the required packages from the PPA:
60+
61+
.. code-block:: console
62+
63+
$ sudo apt install usbbootgui pigpio python3-gpiozero python3-pigpio
64+
65+
Access the GPIOs
66+
----------------
67+
68+
Once your PC or Pi has the USB Boot GUI tool installed, connecting a Pi Zero
69+
will automatically launch a prompt to select a role for the device. Select
70+
"GPIO expansion board" and continue:
71+
72+
.. image:: images/gpio-expansion-prompt.png
73+
74+
It will take 30 seconds or so to flash it, then the dialogue will disappear.
75+
76+
Raspberry Pi Desktop and Raspbian will name your Pi Zero connection ``usb0``. On
77+
Ubuntu, this will likely be something else. You can ping it (be sure to use
78+
``ping6`` as it's IPv6 only) using the address ``fe80::1%`` followed by the
79+
connection string. You can look this up using ``ifconfig``.
80+
81+
Set the ``GPIOZERO_PIN_FACTORY`` and ``PIGPIO_ADDR`` environment variables on
82+
your PC so GPIO Zero connects to the "remote" Pi Zero:
83+
84+
.. code-block:: console
85+
86+
$ export GPIOZERO_PIN_FACTORY=pigpio
87+
$ export PIGPIO_ADDR=fe80::1%usb0
88+
89+
Now any GPIO Zero code you run on the PC will use the GPIOs of the attached Pi
90+
Zero:
91+
92+
.. image:: images/gpio-expansion-example.png
93+
94+
Alternatively, you can set the pin factory in-line, as explained in
95+
:doc`remote_gpio`.
96+
97+
Read more on the GPIO expander in blog posts on `raspberrypi.org`_ and
98+
`bennuttall.com`_.
99+
100+
Legacy method - SD card required
101+
================================
102+
103+
The legacy method requires the Pi Zero to have a Raspbian SD card inserted.
104+
105+
Start by creating a Raspbian (desktop or lite) SD card, and then configure the
106+
boot partition like so:
107+
108+
1. Edit ``config.txt`` and add ``dtoverlay=dwc2`` on a new line, then save the
109+
file.
110+
111+
2. Create an empty file called ``ssh`` (no file extension) and save it in the
112+
boot partition.
113+
114+
3. Edit ``cmdline.txt`` and insert ``modules-load=dwc2,g_ether`` after
115+
``rootwait``.
116+
117+
(See guides on `blog.gbaman.info`_ and `learn.adafruit.com`_ for more detailed
118+
instructions)
119+
120+
Then connect the Pi Zero to your computer using a micro USB cable (connecting it
121+
to the USB port, not the power port). You'll see the indicator LED flashing as
122+
the Pi Zero boots. When it's ready, you will be able to ping and SSH into it
123+
using the hostname ``raspberrypi.local``. SSH into the Pi Zero, install pigpio
124+
and run the pigpio daemon.
125+
126+
Then, drop out of the SSH session and you can run Python code on your computer
127+
to control devices attached to the Pi Zero, referencing it by its hostname (or
128+
IP address if you know it), for example:
129+
130+
.. code-block:: console
131+
132+
$ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=raspberrypi.local python3 led.py
133+
134+
135+
.. _Raspberry Pi Zero: https://www.raspberrypi.org/products/raspberry-pi-zero/
136+
.. _Pi Zero W: https://www.raspberrypi.org/products/raspberry-pi-zero-w/
137+
.. _raspberrypi.org: https://www.raspberrypi.org/blog/gpio-expander/
138+
.. _bennuttall.com: http://bennuttall.com/raspberry-pi-zero-gpio-expander/
139+
.. _blog.gbaman.info: http://blog.gbaman.info/?p=791
140+
.. _learn.adafruit.com: https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/ethernet-gadget

‎docs/remote_gpio.rst‎

Lines changed: 2 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -315,133 +315,9 @@ remotely.
315315
Pi Zero USB OTG
316316
===============
317317

318-
The `Raspberry Pi Zero`_ and `Pi Zero W`_ feature a USB OTG port, allowing users
319-
to configure the device as (amongst other things) an Ethernet device. In this
320-
mode, it is possible to control the Pi Zero's GPIO pins over USB from another
321-
computer using remote pins.
318+
Continue to:
322319

323-
GPIO expander method - no SD card required
324-
------------------------------------------
325-
326-
The GPIO expander method allows you to boot the Pi Zero over USB from the PC,
327-
without an SD card. Your PC sends the required boot firmware to the Pi over the
328-
USB cable, launching a mini version of Raspbian and booting it in RAM. The OS
329-
then starts the pigpio daemon, allowing "remote" access over the USB cable.
330-
331-
At the time of writing, this is only possible using either the Raspberry Pi
332-
Desktop x86 OS, or Ubuntu (or a derivative), or from another Raspberry Pi. Usage
333-
from Windows and Mac OS is not supported at present.
334-
335-
Raspberry Pi Desktop x86 setup
336-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
337-
338-
1. Download an ISO of the Raspberry Pi Desktop OS from raspberrypi.org (this
339-
must be the Stretch release, not the older Jessie image).
340-
341-
2. Write the image to a USB stick or burn to a DVD.
342-
343-
3. Live boot your PC or Mac into the OS (select "Run with persistence" and your
344-
computer will be back to normal afterwards).
345-
346-
Raspberry Pi (Raspbian) setup
347-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
348-
349-
1. Update your package list and install the ``usbbootgui`` package:
350-
351-
.. code-block:: console
352-
353-
$ sudo apt update
354-
$ sudo apt install usbbootgui
355-
356-
Ubuntu setup
357-
~~~~~~~~~~~~
358-
359-
1. Add the Raspberry Pi PPA to your system:
360-
361-
.. code-block:: console
362-
363-
$ sudo add-apt-repository ppa:rpi-distro/ppa
364-
365-
2. If you have previously installed ``gpiozero`` or ``pigpio`` with pip,
366-
uninstall these first:
367-
368-
.. code-block:: console
369-
370-
$ sudo pip3 uninstall gpiozero pigpio
371-
372-
3. Install the required packages from the PPA:
373-
374-
.. code-block:: console
375-
376-
$ sudo apt install usbbootgui pigpio python3-gpiozero python3-pigpio
377-
378-
Access the GPIOs
379-
~~~~~~~~~~~~~~~~
380-
381-
Once your PC or Pi has the USB Boot GUI tool installed, connecting a Pi Zero
382-
will automatically launch a prompt to select a role for the device. Select
383-
"GPIO expansion board" and continue:
384-
385-
.. image:: images/gpio-expansion-prompt.png
386-
387-
It will take 30 seconds or so to flash it, then the dialogue will disappear.
388-
389-
Raspberry Pi Desktop and Raspbian will name your Pi Zero connection ``usb0``. On
390-
Ubuntu, this will likely be something else. You can ping it (be sure to use
391-
``ping6`` as it's IPv6 only) using the address ``fe80::1%`` followed by the
392-
connection string. You can look this up using ``ifconfig``.
393-
394-
Set the ``GPIOZERO_PIN_FACTORY`` and ``PIGPIO_ADDR`` environment variables on
395-
your PC so GPIO Zero connects to the "remote" Pi Zero:
396-
397-
.. code-block:: console
398-
399-
$ export GPIOZERO_PIN_FACTORY=pigpio
400-
$ export PIGPIO_ADDR=fe80::1%usb0
401-
402-
Now any GPIO Zero code you run on the PC will use the GPIOs of the attached Pi
403-
Zero:
404-
405-
.. image:: images/gpio-expansion-example.png
406-
407-
Alternatively, you can set the pin factory in-line, as explained above.
408-
409-
Read more on the GPIO expander in blog posts on `raspberrypi.org`_ and
410-
`bennuttall.com`_.
411-
412-
Legacy method - SD card required
413-
--------------------------------
414-
415-
The legacy method requires the Pi Zero to have a Raspbian SD card inserted.
416-
417-
Start by creating a Raspbian (desktop or lite) SD card, and then configure the
418-
boot partition like so:
419-
420-
1. Edit ``config.txt`` and add ``dtoverlay=dwc2`` on a new line, then save the
421-
file.
422-
423-
2. Create an empty file called ``ssh`` (no file extension) and save it in the
424-
boot partition.
425-
426-
3. Edit ``cmdline.txt`` and insert ``modules-load=dwc2,g_ether`` after
427-
``rootwait``.
428-
429-
(See guides on `blog.gbaman.info`_ and `learn.adafruit.com`_ for more detailed
430-
instructions)
431-
432-
Then connect the Pi Zero to your computer using a micro USB cable (connecting it
433-
to the USB port, not the power port). You'll see the indicator LED flashing as
434-
the Pi Zero boots. When it's ready, you will be able to ping and SSH into it
435-
using the hostname ``raspberrypi.local``. SSH into the Pi Zero, install pigpio
436-
and run the pigpio daemon.
437-
438-
Then, drop out of the SSH session and you can run Python code on your computer
439-
to control devices attached to the Pi Zero, referencing it by its hostname (or
440-
IP address if you know it), for example:
441-
442-
.. code-block:: console
443-
444-
$ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=raspberrypi.local python3 led.py
320+
* :doc:`pi_zero_otg`
445321

446322

447323
.. _RPi.GPIO: https://pypi.python.org/pypi/RPi.GPIO
@@ -451,9 +327,3 @@ IP address if you know it), for example:
451327
.. _get-pip: https://pip.pypa.io/en/stable/installing/
452328
.. _following this guide: https://www.raspberrypi.org/learning/using-pip-on-windows/worksheet/
453329
.. _Sense HAT: https://www.raspberrypi.org/products/sense-hat/
454-
.. _Raspberry Pi Zero: https://www.raspberrypi.org/products/raspberry-pi-zero/
455-
.. _Pi Zero W: https://www.raspberrypi.org/products/raspberry-pi-zero-w/
456-
.. _raspberrypi.org: https://www.raspberrypi.org/blog/gpio-expander/
457-
.. _bennuttall.com: http://bennuttall.com/raspberry-pi-zero-gpio-expander/
458-
.. _blog.gbaman.info: http://blog.gbaman.info/?p=791
459-
.. _learn.adafruit.com: https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/ethernet-gadget

0 commit comments

Comments
 (0)