Raspberry Pi Documentation - Raspberry Pi OS
Raspberry Pi Documentation - Raspberry Pi OS
Introduction
Edit this on GitHub
Raspberry Pi OS is a free operating system based on Debian, optimised for the Raspberry Pi
hardware, and is the recommended operating system for normal use on a Raspberry Pi. The OS
comes with over 35,000 packages: pre-compiled software bundled in a nice format for easy
installation on your Raspberry Pi.
Raspberry Pi OS is under active development, with an emphasis on improving the stability and
performance of as many Debian packages as possible on Raspberry Pi.
It’s important to keep your Raspberry Pi up to date. The first and probably the most important
reason is security. A device running Raspberry Pi OS contains millions of lines of code that you
rely on. Over time, these millions of lines of code will expose well-known vulnerabilities, which
are documented in publicly available databases meaning that they are easy to exploit. The only
way to mitigate these exploits as a user of Raspberry Pi OS is to keep your software up to date,
as the upstream repositories track CVEs closely and try to mitigate them quickly.
The second reason, related to the first, is that the software you are running on your device most
certainly contains bugs. Some bugs are CVEs, but bugs could also be affecting the desired
functionality without being related to security. By keeping your software up to date, you are
lowering the chances of hitting these bugs.
Using APT
The easiest way to manage installing, upgrading, and removing software is using APT
(Advanced Packaging Tool) from Debian. To update software in Raspberry Pi OS, you can use
the apt tool from a Terminal window.
Next, upgrade all your installed packages to their latest versions with the following command:
Note that full-upgrade is used in preference to a simple upgrade, as it also picks up any
dependency changes that may have been made.
Generally speaking, doing this regularly will keep your installation up to date for the particular
major Raspberry Pi OS release you are using (e.g. Buster). It will not update from one major
release to another, for example, Stretch to Buster or Buster to Bullseye.
However, there are occasional changes made in the Raspberry Pi OS image that require manual
intervention, for example a newly introduced package. These are not installed with an upgrade,
as this command only updates the packages you already have installed.
NOTE
The kernel and firmware are installed as a Debian package, and so will also get updates
when using the procedure above. These packages are updated infrequently and after
extensive testing.
If moving an existing SD card to a new Raspberry Pi model (for example the Raspberry Pi Zero 2
W), you may also need to update the kernel and the firmware first using the instructions above.
When running sudo apt full-upgrade, it will show how much data will be downloaded and how
much space it will take up on the SD card. It’s worth checking with df -h that you have enough
free disk space, as unfortunately apt will not do this for you. Also be aware that downloaded
package files (.deb files) are kept in /var/cache/apt/archives. You can remove these in order
to free up space with sudo apt clean (sudo apt-get clean in older releases of apt).
WARNING
The latest version of Raspberry Pi OS is based on Debian Bullseye. The previous version was
based on Buster. If you want to perform an in-place upgrade from Buster to Bullseye (and you’re
aware of the risks) see the instructions in the forums.
You can search the archives for a package with a given keyword with apt-cache search:
You can view more information about a package before installing it with apt-cache show:
apt-cache show sl
Package: sl
Version: 3.03-17
Architecture: armhf
Maintainer: Hiroyuki Yamamoto <[email protected]>
Installed-Size: 114
Depends: libc6 (>= 2.4), libncurses5 (>= 5.5-5~), libtinfo5
Homepage: http://www.tkl.iis.u-tokyo.ac.jp/~toyoda/index_e.html
Priority: optional
Section: games
Filename: pool/main/s/sl/sl_3.03-17_armhf.deb
Size: 26246
SHA256: 42dea9d7c618af8fe9f3c810b3d551102832bf217a5bcdba310f119f62117dfb
SHA1: b08039acccecd721fc3e6faf264fe59e56118e74
MD5sum: 450b21cc998dc9026313f72b4bd9807b
Description: Correct you if you type `sl' by mistake
Sl is a program that can display animations aimed to correct you
if you type 'sl' by mistake.
SL stands for Steam Locomotive.
Typing this command should inform the user how much disk space the package will take up
and asks for confirmation of the package installation. Entering Y (or just pressing Enter, as yes
is the default action) will allow the installation to occur. This can be bypassed by adding the -y
flag to the command:
The user is prompted to confirm the removal. Again, the -y flag will auto-confirm.
You can also choose to completely remove the package and its associated configuration files
with apt purge:
Using rpi-update
rpi-update is a command line application that will update your Raspberry Pi OS kernel and
VideoCore firmware to the latest pre-release versions.
WARNING
Pre-release versions of software are not guaranteed to work. You should not use rpi-update
on any system unless recommended to do so by a Raspberry Pi engineer. It may leave your
system unreliable or even completely broken. It should not be used as part of any regular
update process.
The rpi-update script was originally written by Hexxeh, but is now supported by Raspberry Pi
engineers. The script source is in the rpi-update repository.
What it does
rpi-update will download the latest pre-release version of the linux kernel, its matching
modules, device tree files, along with the latest versions of the VideoCore firmware. It will then
install these files to relevant locations on the SD card, overwriting any previous versions.
All the source data used by rpi-update comes from the rpi-firmware repository. This repository
simply contains a subset of the data from the official firmware repository, as not all the data
from that repo is required.
Running rpi-update
If you are sure that you need to use rpi-update, it is advisable to take a backup of your current
system first as running rpi-update could result in a non-booting system.
rpi-update needs to be run as root. Once the update is complete you will need to reboot.
sudo rpi-update
sudo reboot
If you have done an rpi-update and things are not working as you wish, if your Raspberry Pi is
still bootable you can return to the stable release using:
You will need to reboot your Raspberry Pi for these changes to take effect.
WARNING
The following documentation refers to Raspberry Pi OS Buster and earlier versions. OMXPlayer
has been deprecated in the latest OS release. If you are running Bullseye, VLC is now the
recommended alternative.
The simplest way of playing audio and video on Raspberry Pi is to use the installed OMXPlayer
application.
This is hardware accelerated, and can play back many popular audio and video file formats.
OMXPlayer uses the OpenMAX (omx) hardware acceleration interface (API) which is the officially
supported media API on Raspberry Pi. OMXPlayer was developed by the Kodi Project’s Edgar
Hucek.
omxplayer /opt/vc/src/hello_pi/hello_video/test.h264
By default the audio is sent to the analog port. If you are using a HDMI-equipped display device
with speakers, you need to tell omxplayer to send the audio signal over the HDMI link.
When displaying video, the whole display will be used as output. You can specify which part of
the display you want the video to be on using the window option.
You can also specify which part of the video you want to be displayed: this is called a crop
window. This portion of the video will be scaled up to match the display, unless you also use the
window option.
omxplayer example.mp3
This will play the audio file example.mp3 through either your monitor’s built-in speakers or your
headphones, connected via the headphone jack.
If you need an example file you can download one from here using the following command:
wget https://raw.githubusercontent.com/raspberrypilearning/burping-jelly-baby/maste
r/data/la.mp3 -O example.mp3 --no-check-certificate
If you cannot hear anything, make sure your headphones or speakers are connected correctly.
Note that omxplayer doesn’t use ALSA and so ignores the audio configuration set by raspi-
config or amixer.
If omxplayer’s auto-detection of the correct audio output device fails, you can force output over
HDMI with:
Alternatively, you can force output over the headphone jack with:
You can even force output over both the headphone jack and HDMI with:
omxplayer example.mp4
This will play the example.mp4 in full screen. Hit Ctrl + C to exit.
On the Raspberry Pi 4, hardware support for MPEG2 and VC-1 codecs has been removed, so we
recommend the use of the VLC application, which supports these formats in software. In
addition, VLC has hardware support for H264 and the new HEVC codec.
An Example Video
A video sample of the animated film Big Buck Bunny is available on your Raspberry Pi. To play it
enter the following command into a terminal window:
omxplayer /opt/vc/src/hello_pi/hello_video/test.h264
On a Raspberry Pi 4, use the following command for H264 files:
omxplayer /opt/vc/src/hello_pi/hello_video/test.h264
vlc /opt/vc/src/hello_pi/hello_video/test.h264
When using VLC, you can improve playback performance by encapsulating the raw H264
stream, for example from the Raspberry Pi Camera Module. This is easily done using ffmpeg.
Playback is also improved if VLC is run full screen; either select fullscreen from the user
interface, or you can add the --fullscreen options to the vlc command line.
1 decrease speed
2 increase speed
< rewind
> fast forward
z show info
j previous audio stream
k next audio stream
i previous chapter
o next chapter
n previous subtitle stream
m next subtitle stream
s toggle subtitles
w show subtitles
x hide subtitles
d decrease subtitle delay (- 250 ms)
f increase subtitle delay (+ 250 ms)
q exit omxplayer
p / space pause/resume
- decrease volume
+ / = increase volume
left arrow seek -30 seconds
right arrow seek +30 seconds
down arrow seek -600 seconds
up arrow seek +600 seconds
Adding the & at the end of the command runs the job in the background. You can then check the
status of this background job using the jobs command. By default, the job will complete when
omxplayer finishes playing, but if necessary, you can stop it at any point using the kill
command.
$ jobs
[1]- Running omxplayer --no-keys example.mp3 &
$ kill %1
$
[1]- Terminated omxplayer --no-keys example.mp3 &
Rather than using the Raspberry Pi camera module, you can use a standard USB webcam to
take pictures and video on your Raspberry Pi.
NOTE
The quality and configurability of the camera module is highly superior to a standard USB
webcam.
If you are not using the default pi user account, you need to add your username to the video
group, otherwise you will see 'permission denied' errors.
To check that the user has been added to the group correctly, use the groups command.
Basic Usage
Enter the command fswebcam followed by a filename and a picture will be taken using the
webcam, and saved to the filename specified:
fswebcam image.jpg
NOTE
The small default resolution used, and the presence of a banner showing the timestamp.
The webcam used in this example has a resolution of 1280 x 720 so to specify the resolution I
want the image to be taken at, use the -r flag:
Picture now taken at the full resolution of the webcam, with the banner present.
mkdir webcam
To create a script, open up your editor of choice and write the following example code:
#!/bin/bash
DATE=$(date +"%Y-%m-%d_%H%M")
This script will take a picture and name the file with a timestamp. Say we saved it as webcam.sh,
we would first make the file executable:
chmod +x webcam.sh
./webcam.sh
Which would run the commands in the file and give the usual output:
Time-Lapse Captures
You can use cron to schedule taking a picture at a given interval, such as every minute to
capture a time-lapse.
This will either ask which editor you would like to use, or open in your default editor. Once you
have the file open in an editor, add the following line to schedule taking a picture every minute
(referring to the Bash script from above):
* * * * * /home/pi/webcam.sh 2>&1
Ensure your script does not save each picture taken with the same filename. This will overwrite
the picture each time.
Useful Utilities
Edit this on GitHub
tvservice
tvservice is a command line application used to get and set information about the display,
targeted mainly at HDMI video and audio.
Typing tvservice by itself will display a list of available command line options.
-p, --preferred
-o, --off
NOTE
Powering off the output using this command will also destroy any framebuffers/dispmanx
layers associated with the display. These are NOT re-established with a subsequent power
on, so will result in a blank screen.
A better option is to use the vcgencmd display_power option, as this will retain any
framebuffers, so when the power is turned back on the display will be the returned to the
previous power on state.
-t, --ntsc
Use 59.94Hz (NTSC frequency) rather than 60Hz for HDMI mode.
Power on the SDTV (composite output) with the specified mode, PAL or NTSC, and the specified
aspect, 4:3, 14:9, 16:9. The optional P parameter can be used to specify progressive mode.
-m, --modes=Group
-M, --monitor
-s, --status
Shows the current settings for the display mode, including mode, resolution, and frequency.
-a, --audio
Shows the current settings for the audio mode, including channels, sample rate and sample
size.
-d, --dumpid=filename
Save the current EDID to the specified filename. You can then use edidparser <filename> to
display the data in a human readable form.
-j, --json
When used in combination with the --modes options, displays the mode information in JSON
format.
-n, --name
Extracts the display name from the EDID data and shows it.
-l, --list
-v, --device=display
Specifies the ID of the device to use; see the output of --list for available IDs.
vcgencmd
The vcgencmd tool is used to output information from the VideoCore GPU on the Raspberry Pi.
You can find source code for the vcgencmd utility on Github.
To get a list of all commands which vcgencmd supports, use vcgencmd commands. Some useful
commands and their required parameters are listed below.
vcos
version displays the build date and version of the firmware on the VideoCore
log status displays the error log status of the various VideoCore firmware areas
version
Displays the enabled and detected state of the Raspberry Pi camera: 1 means yes, 0 means no.
Whilst all firmware except cutdown versions support the camera, this support needs to be
enabled by using raspi-config.
get_throttled
Returns the throttled state of the system. This is a bit-pattern - a bit being set indicates the
following meanings:
measure_temp
Returns the temperature of the SoC as measured by its internal temperature sensor; on
Raspberry Pi 4, measure_temp pmic returns the temperature of the PMIC.
measure_clock [clock]
This returns the current frequency of the specified clock. The options are:
clock Description
v3d 3D block
uart UART
hdmi HDMI
measure_volts [block]
block Description
otp_dump
Displays the content of the OTP (one-time programmable) memory inside the SoC. These are
32-bit values, indexed from 8 to 64. See the OTP bits page for more details.
Display value of the configuration setting specified: alternatively, specify either int (integer) or
str (string) to see all configuration items of the given type. For example:
get_mem type
Reports on the amount of memory addressable by the ARM and the GPU. To show the amount
of ARM-addressable memory use vcgencmd get_mem arm; to show the amount of GPU-
addressable memory use vcgencmd get_mem gpu. Note that on devices with more than 1GB of
memory the arm parameter will always return 1GB minus the gpu memory value, since the GPU
firmware is only aware of the first 1GB of memory. To get an accurate report of the total
memory on the device, see the total_mem configuration item - see get_config section above.
codec_enabled [type]
Reports whether the specified CODEC type is enabled. Possible options for type are AGIF, FLAC,
H263, H264, MJPA, MJPB, MJPG, MPG2, MPG4, MVC0, PCM, THRA, VORB, VP6, VP8, WMV9,
WVC1. Those highlighted currently require a paid for licence (see the this config.txt section for
more info), except on the Raspberry Pi 4 and 400, where these hardware codecs are disabled in
preference to software decoding, which requires no licence. Note that because the H.265 HW
block on the Raspberry Pi 4 and 400 is not part of the VideoCore GPU, its status is not accessed
via this command.
get_lcd_info
mem_oom
Displays statistics on any OOM (out of memory) events occurring in the VideoCore memory
space.
mem_reloc_stats
read_ring_osc
Returns the current speed voltage and temperature of the ring oscillator.
hdmi_timings
Displays the current HDMI settings timings. See Video Config for details of the values returned.
dispmanx_list
Note that for the 7" Raspberry Pi Touch Display this simply turns the backlight on and off. The
touch functionality continues to operate as normal.
vcgencmd display_power 0 7 will turn off power to display ID 7, which is HDMI 1 on a Raspberry
Pi 4.
Display ID
Main LCD 0
Secondary LCD 1
HDMI 0 2
Composite 3
HDMI 1 7
vcdbg
vcdbg is an application to help with debugging the VideoCore GPU from Linux running on the
ARM. It needs to be run as root. This application is mostly of use to Raspberry Pi engineers,
although there are some commands that general users may find useful.
NOTE
version
log
log Description
malloc
reloc
Without any further parameters, lists the current status of the relocatable allocator. Use sudo
vcdbg reloc small to list small allocations as well.
Use the subcommand sudo vcdbg reloc stats to list statistics for the relocatable allocator.
hist
Use sudo vcdbg hist gnuplot to dump task history in gnuplot format to task.gpt and task.dat
A powerful feature of the Raspberry Pi is the row of GPIO (general-purpose input/output) pins
along the top edge of the board. A 40-pin GPIO header is found on all current Raspberry Pi
boards (unpopulated on Raspberry Pi Zero, Raspberry Pi Zero W and Raspberry Pi Zero 2 W).
Prior to the Raspberry Pi 1 Model B+ (2014), boards comprised a shorter 26-pin header. The
GPIO header on all boards (including the Raspberry Pi 400) have a 0.1" (2.54mm) pin pitch.
Any of the GPIO pins can be designated (in software) as an input or output pin and used for a
wide range of purposes.
NOTE
The numbering of the GPIO pins is not in numerical order; GPIO pins 0 and 1 are present on
the board (physical pins 27 and 28) but are reserved for advanced use (see below).
Voltages
Two 5V pins and two 3.3V pins are present on the board, as well as a number of ground pins
(0V), which are unconfigurable. The remaining pins are all general purpose 3.3V pins, meaning
outputs are set to 3.3V and inputs are 3.3V-tolerant.
Outputs
A GPIO pin designated as an output pin can be set to high (3.3V) or low (0V).
Inputs
A GPIO pin designated as an input pin can be read as high (3.3V) or low (0V). This is made
easier with the use of internal pull-up or pull-down resistors. Pins GPIO2 and GPIO3 have fixed
pull-up resistors, but for other pins this can be configured in software.
More
As well as simple input and output devices, the GPIO pins can be used with a variety of
alternative functions, some are available on all pins, others on specific pins.
SPI
SPI0: MOSI (GPIO10); MISO (GPIO9); SCLK (GPIO11); CE0 (GPIO8), CE1 (GPIO7)
SPI1: MOSI (GPIO20); MISO (GPIO19); SCLK (GPIO21); CE0 (GPIO18); CE1 (GPIO17);
CE2 (GPIO16)
I2C
Serial
TX (GPIO14); RX (GPIO15)
GPIO pinout
A handy reference can be accessed on the Raspberry Pi by opening a terminal window and
running the command pinout. This tool is provided by the GPIO Zero Python library, which is
installed by default in Raspberry Pi OS.
For more details on the advanced capabilities of the GPIO pins see gadgetoid’s interactive
pinout diagram.
WARNING
While connecting up simple components to the GPIO pins is perfectly safe, it’s important to
be careful how you wire things up. LEDs should have resistors to limit the current passing
through them. Do not use 5V for 3.3V components. Do not connect motors directly to the
GPIO pins, instead use an H-bridge circuit or a motor controller board.
Permissions
In order to use the GPIO ports your user must be a member of the gpio group. The pi user is a
member by default, other users need to be added manually.
GPIO in Python
Using the GPIO Zero library makes it easy to get started with controlling GPIO devices with
Python. The library is comprehensively documented at gpiozero.readthedocs.io.
LED
led = LED(17)
while True:
led.on()
sleep(1)
led.off()
sleep(1)
Run this in an IDE like Thonny, and the LED will blink on and off repeatedly.
Button
To read the state of a button connected to GPIO2, you can use this code:
button = Button(2)
while True:
if button.is_pressed:
print("Pressed")
else:
print("Released")
sleep(1)
Button functionality includes the properties is_pressed and is_held; callbacks when_pressed,
when_released, and when_held; and methods wait_for_press() and wait_for_release.
Button + LED
To connect the LED and button together, you can use this code:
led = LED(17)
button = Button(2)
while True:
if button.is_pressed:
led.on()
else:
led.off()
Alternatively:
led = LED(17)
button = Button(2)
while True:
button.wait_for_press()
led.on()
button.wait_for_release()
led.off()
or:
led = LED(17)
button = Button(2)
button.when_pressed = led.on
button.when_released = led.off
Going further
You can find more information on how to program
electronics connected to your Raspberry Pi with the
GPIO Zero Python library in the Raspberry Pi Press
book Simple Electronics with GPIO Zero. Written by
Phil King, it is part of the MagPi Essentials series
published by Raspberry Pi Press. The book gets you
started with the GPIO Zero library, and walks you
through how to use it by building a series of projects.
Raspberry Pi documentation is copyright © 2012-2023 Raspberry Pi Ltd and is licensed under a Creative Commons Attribution-ShareAlike 4.0
International (CC BY-SA) licence.
Some content originates from the eLinux wiki, and is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported licence.
The terms HDMI, HDMI High-Definition Multimedia Interface, HDMI trade dress and the HDMI Logos are trademarks or registered trademarks of HDMI
Licensing Administrator, Inc