Skip to content

Commit 69563df

Browse files
author
Alasdair Allan
authored
Merge pull request #2658 from raspberrypi/develop
Push to production
2 parents 5a6cb59 + e430a12 commit 69563df

36 files changed

+540
-0
lines changed

‎documentation/asciidoc/accessories/audio.adoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
include::audio/introduction.adoc[]
3+
4+
include::audio/dac_pro.adoc[]
5+
6+
include::audio/dac_plus.adoc[]
7+
8+
include::audio/digiamp_plus.adoc[]
9+
10+
include::audio/codec_zero.adoc[]
11+
12+
include::audio/configuration.adoc[]
13+
14+
include::audio/getting_started.adoc[]
15+
16+
include::audio/advanced.adoc[]
17+
18+
include::audio/faq.adoc[]
19+

‎documentation/asciidoc/accessories/audio/advanced.adoc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
== Hardware information
2+
3+
=== GPIO usage
4+
5+
Raspberry Pi audio boards take advantage of a number of pins on the GPIO header in
6+
order to operate successfully. Some of these pins are solely for the use of the board, and
7+
some can be shared with other peripherals, sensors, etc.
8+
9+
The following Raspberry Pi GPIO pins will be used by the audio boards:
10+
11+
* All power pins
12+
* All ground pins
13+
* GPIO 2/3 (I2C)
14+
* GPIO 18/19/20/21 (I2S)
15+
16+
If appropriate then the following are also used:
17+
18+
* GPIO 22 (DigiAMP+ mute/unmute support)
19+
* GPIO 23/24 for rotary encoder (physical volume control) or status LED (Codec Zero)
20+
* GPIO 25 for the IR Sensor
21+
* GPIO 27 for the rotary encoder push switch/Code Zero switch
22+
23+
=== DAC PRO, DAC{plus}, DigiAMP{plus}, Codec Zero
24+
25+
image::images/pin_table_new.jpg[width="80%"]
26+
27+
The DAC PRO, DAC{plus} and DigiAMP{plus} re-expose the Raspberry Pi signals, allowing additional sensors and peripherals
28+
to be added easily. Please note that some signals are for exclusive use (I2S and EEPROM) by some
29+
of our boards; others such as I2C can be shared across multiple boards.
30+
31+
image::images/pin_out_new.jpg[width="80%"]
32+
33+
34+
35+

‎documentation/asciidoc/accessories/audio/codec_zero.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
=== Raspberry Pi Codec Zero
2+
3+
Raspberry Pi Codec Zero is a Raspberry Pi Zero-sized audio HAT. It delivers bi-directional digital audio signals (I2S) between a Raspberry Pi and the Codec Zero's on-board Dialog Semiconductor DA7212 codec. The Codec Zero supports a range of input and output devices.
4+
5+
* High performance 24-bit audio codec
6+
* Supports common audio sample rates between 8-96kHz
7+
* Built in micro-electro-mechanical (MEMS) microphone (Mic2)
8+
* Mono electret microphone (Mic2 left)
9+
* Automatic MEMS disabling on Mic2 insert detect
10+
* Supports additional (no fit) mono electret microphone (Mic1 right)
11+
* Stereo auxiliary input channel (AUX IN) - PHONO/RCA connectors
12+
* Stereo auxiliary output channel (Headphone/AUX OUT)
13+
* Flexible analogue and digital mixing paths
14+
* Digital signal processors (DSP) for automatic level control (ALC)
15+
* Five-band EQ
16+
* Mono line-out/mini speaker driver: 1.2W @ 5V, THD<10%, R=8Ω
17+
18+
image::images/Codec_Zero_Board_Diagram.jpg[width="80%"]
19+
20+
The Codec Zero includes an EEPROM which can be used for auto-configuration of the Linux environment if necessary. It has an integrated MEMS microphone, and can be used with stereo microphone input via a 3.5mm socket and a mono speaker (1.2W/8Ω).
21+
22+
In addition to the green (GPIO23) and red (GPIO24) LEDs, a tactile programmable button (GPIO27) is also provided.
23+
24+
==== Pinouts
25+
[cols="1,12"]
26+
|===
27+
| *P1/2* | Support external PHONO/RCA sockets if needed. P1: AUX IN, P2: AUX OUT.
28+
| *P1* | Pin 1 is square.
29+
|===
30+
image::images/CODEC_ZERO_ZOOMED_IN_DIAGRAM.jpg[width="50%"]
31+
32+
Codec Zero is an ideal design starting point for small-scale projects such as walkie-talkies, smart doorbells, vintage radio hacks, or smart speakers.

‎documentation/asciidoc/accessories/audio/configuration.adoc‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
== Configuration
2+
3+
A pre-programmed EEPROM is included on all Raspberry Pi audio boards. Raspberry Pi audio boards are designed to be plug-and-play; Raspberry Pi OS is able to automatically detect and configure itself. In Raspberry Pi OS, right-clicking on the audio settings in the top right-hand corner of your screen will allow you to switch between the on-board audio settings and the HAT audio settings:
4+
5+
image::images/gui.png[]
6+
7+
There are a number of third-party audio software applications available for Raspberry Pi that will support the plug-and-play feature of our audio boards. Often these are used headless. They can be controlled via a PC or Mac application, or by a web server installed on Raspberry Pi, with interaction through a webpage.
8+
9+
If you need to configure Raspberry Pi OS yourself, perhaps if you're running a headless system of your own and don't have the option of control via the GUI, you will need to make your Raspberry Pi audio board the primary audio device in Raspberry Pi OS, disabling the Raspberry Pi’s on-board audio device. This is done by editing the `/boot/config.txt` file. Using a Terminal session connected to your Raspberry Pi via SSH, run the following command to edit the file:
10+
11+
----
12+
$ sudo nano /boot/config.txt
13+
----
14+
15+
Find the `dtparam=audio=on` line in the file and comment it out by placing a # symbol at the start of the line. Anything written after the # symbol in any given line will be disregarded by the program. Your ``/boot/config.txt`` file should now have the following entry:
16+
17+
----
18+
#dtparam=audio=on
19+
----
20+
21+
Press CTRL+X, then Y and Enter to save, followed by a reboot of your Raspberry Pi in order for the settings to take effect.
22+
23+
----
24+
$ sudo reboot
25+
----
26+
27+
Alternatively, the `/boot/config.txt` file can be edited directly onto the Raspberry Pi's microSD card, inserted into your usual computer. Using the default file manager, open the `boot` volume on the card and edit the `config.txt` file using an appropriate text editor, then save the file, eject the microSD card and reinsert it back into your Raspberry Pi.
28+
29+
=== Attaching the HAT
30+
31+
The Raspberry Pi audio boards attach to the Raspberry Pi’s 40-pin header. They are designed to be supported on the Raspberry Pi using the supplied circuit board standoffs and screws. No soldering is required on the Raspberry Pi audio boards for normal operation unless you are using hardwired connections for specific connectors such as XLR (External Line Return) connections on the DAC Pro.
32+
33+
All the necessary mounting hardware including spacers, screws and connectors is provided. The PCB spacers should be screwed, finger-tight only, to the Raspberry Pi before adding the audio board. The remaining screws should then be screwed into the spacers from above.
34+
35+
=== Codec Zero configuration
36+
37+
The Raspberry Pi Codec Zero board uses the Dialog Semiconductor DA7212 codec. This allows
38+
the recording of audio from the built-in MEMS microphone, from stereo phono sockets (AUX
39+
IN) or two mono external electret microphones. Playback is through stereo phono sockets (AUX OUT)
40+
or a mono speaker connector.
41+
42+
Each input and output device has its own mixer, allowing the audio levels and volume to be adjusted
43+
independently. Within the codec itself, other mixers and switches exist to allow the output to be mixed to a single mono channel for single-speaker output. Signals may also be inverted; there is a five-band equaliser to adjust certain frequency bands. These settings can be controlled interactively, using AlsaMixer, or programmatically.
44+
45+
Both the AUX IN and AUX OUT are 1V RMS. It may be necessary to adjust
46+
the AUX IN’s mixer to ensure that the input signal doesn’t saturate the ADC. Similarly, the output mixers can be to be adjusted to get the best possible output.
47+
48+
Preconfigured scripts (loadable ALSA settings) https://github.com/iqaudio/Pi-Codec[are available on GitHub], offering:
49+
50+
* Mono MEMS mic recording, mono speaker playback
51+
* Mono MEMS mic recording, mono AUX OUT playback
52+
* Stereo AUX IN recording, stereo AUX OUT playback
53+
* Stereo MIC1/MIC2 recording, stereo AUX OUT playback
54+
55+
The Codec Zero needs to know which of these input and output settings are being used each time the Raspberry Pi powers on. Using a Terminal session on your Raspberry Pi, run the following command to download the scripts:
56+
57+
----
58+
$ git clone https://github.com/iqaudio/Pi-Codec.git
59+
----
60+
61+
If git is not installed, run the following command to install it:
62+
63+
----
64+
$ sudo apt install git
65+
----
66+
67+
The following command will set your device to use the on-board MEMS microphone and output for speaker playback:
68+
69+
----
70+
$ sudo alsactl restore -f /home/pi/Pi-Codec/IQaudIO_Codec_OnboardMIC_record_and_SPK_playback.state
71+
----
72+
73+
In order for your project to operate with your required settings when it is powered on, edit the `/etc/rc.local` file. The contents of this file are run at the end of every boot process, so it is ideal for this purpose. Edit the file:
74+
75+
----
76+
$ sudo nano /etc/rc.local
77+
----
78+
79+
Add the chosen script command above the exit 0 line and then Ctrl X, Y and Enter to save. The file should now look similar to this depending on your chosen setting:
80+
81+
----
82+
#!/bin/sh -e
83+
#
84+
# rc.local
85+
#
86+
# This script is executed at the end of each multiuser runlevel.
87+
# Make sure that the script will "exit 0" on success or any other
88+
# value on error.
89+
#
90+
# In order to enable or disable this script just change the execution
91+
# bits.
92+
#
93+
# By default this script does nothing.
94+
95+
sudo alsactl restore -f /home/pi/Pi-Codec/IQaudIO_Codec_OnboardMIC_record_and_SPK_playback.state
96+
97+
exit 0
98+
----
99+
100+
Ctrl X, Y and Enter to save and reboot your device for the settings to take effect:
101+
102+
----
103+
$ sudo reboot
104+
----
105+
106+
If you are using your Raspberry Pi and Codec Zero in a headless environment, there is one final step required to make the Codec Zero the default audio device without access to the GUI audio settings on the desktop. We need to create a small file in your home folder:
107+
108+
----
109+
$ sudo nano ./asoundrc
110+
----
111+
112+
Add the following to the file:
113+
114+
----
115+
pcm.!default {
116+
type hw
117+
card Zero
118+
}
119+
----
120+
121+
Ctrl X, Y and Enter to save, and reboot once more to complete the configuration:
122+
123+
----
124+
$ sudo reboot
125+
----
126+
127+
=== Muting and unmuting the DigiAMP{plus}
128+
129+
The DigiAMP{plus} mute state is toggled by GPIO22 on Raspberry Pi. The latest audio device tree
130+
supports the unmute of the DigiAMP{plus} through additional parameters.
131+
132+
Firstly a "one-shot" unmute when kernel module loads.
133+
134+
----
135+
dtoverlay=iqaudio-dacplus,unmute_amp
136+
----
137+
138+
Unmute the amp when an ALSA device is opened by a client. Mute, with a five-second delay
139+
when the ALSA device is closed. (Reopening the device within the five-second close
140+
window will cancel mute.)
141+
142+
----
143+
dtoverlay=iqaudio-dacplus,auto_mute_amp
144+
----
145+
146+
If you do not want to control the mute state through the device tree, you can also script your own
147+
solution.
148+
149+
The amp will start up muted. To unmute the amp:
150+
151+
----
152+
$ sudo sh -c "echo 22 > /sys/class/gpio/export"
153+
$ sudo sh -c "echo out >/sys/class/gpio/gpio22/direction"
154+
$ sudo sh -c "echo 1 >/sys/class/gpio/gpio22/value"
155+
----
156+
157+
to mute the amp once more:
158+
159+
----
160+
$ sudo sh -c "echo 0 >/sys/class/gpio/gpio22/value"
161+
----

‎documentation/asciidoc/accessories/audio/dac_plus.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
=== Raspberry Pi DAC{plus}
2+
3+
Raspberry Pi DAC{plus} is a high-resolution audio output HAT that provides 24-bit 192kHz digital audio output.
4+
5+
image::images/DAC+_Board_Diagram.jpg[width="80%"]
6+
7+
A Texas Instruments PCM5122 is used in the DAC{plus} to deliver analogue audio to the phono connectors of the device. It also supports a dedicated headphone amplifier and is powered via the Raspberry Pi through the GPIO header.
8+
9+
==== Pinouts
10+
[cols="1,12"]
11+
|===
12+
| *P1* | Analogue out (0-2V RMS), carries GPIO27, MUTE signal (headphone detect), left and right
13+
audio and left and right ground.
14+
| *P6* | Headphone socket signals (pin1: LEFT, 2:GROUND, 3: RIGHT, 4:GROUND, 5:DETECT).
15+
|===

‎documentation/asciidoc/accessories/audio/dac_pro.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
=== Raspberry Pi DAC Pro
2+
3+
The Raspberry Pi DAC Pro HAT is our highest-fidelity digital to analogue converter (DAC).
4+
5+
image::images/DAC_Pro_Board_Diagram.jpg[width="80%"]
6+
7+
With the Texas Instruments PCM5242, the DAC Pro provides outstanding signal-to-noise ratio (SNR)
8+
and supports balanced/differential output in parallel to phono/RCA line-level output. It also includes a
9+
dedicated headphone amplifier. The DAC Pro is powered by a Raspberry Pi through the GPIO header.
10+
11+
As part of the DAC Pro, two three-pin headers (P7/P9) are exposed above the Raspberry Pi's USB and Ethernet ports for use by the optional XLR board, allowing differential/balanced output.
12+
13+
==== Pinouts
14+
[cols="1,12"]
15+
|===
16+
| *P1* | Analogue out (0-2V RMS), carries GPIO27, MUTE signal (headphone detect), left and right
17+
audio and left and right ground.
18+
| *P6* | Headphone socket signals (1: LEFT, 2: GROUND, 3: RIGHT, 4: GROUND, 5: DETECT).
19+
| *P7/9* | Differential (0-4V RMS) output (P7: LEFT, P9: RIGHT).
20+
| *P10* | Alternative 5V input, powering Raspberry Pi in parallel.
21+
|===

‎documentation/asciidoc/accessories/audio/digiamp_plus.adoc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
=== Raspberry Pi DigiAMP{plus}
2+
3+
With Raspberry Pi DigiAMP{plus}, you can connect passive stereo speakers up to 2x35W with variable output, making it ideal for use in Raspberry Pi-based hi-fi systems.
4+
5+
DigiAMP{plus} uses the Texas Instruments TAS5756M PowerDAC and must be powered from an external supply. It requires a 12-24V DC power source (the XP Power VEC65US19 power supply is recommended).
6+
7+
image::images/DigiAMP+_Board_Diagram.jpg[width="80%"]
8+
9+
DigiAMP{plus}’s power in barrel connector is 5.5mm x 2.5mm.
10+
11+
At power-on, the amplifier is muted by default (the mute LED is illuminated). Software is responsible for the mute state and LED control (Raspberry Pi GPIO22).
12+
13+
DigiAMP{plus} is designed to provide power to the Raspberry Pi and DigiAMP{plus} together in parallel, delivering 5.1V at 2.5amp to the Raspberry Pi through the GPIO header.
14+
15+
WARNING: Do not apply power to the Raspberry Pi's own power input when using DigiAMP{plus}.
16+
17+
==== Pinouts
18+
[cols="1,12"]
19+
|===
20+
| *P5* | Alternative power input for hard wired installations (polarity must be observed).
21+
| *P8* | TAS5756m Internal GPIO1/2/3
22+
|===

‎documentation/asciidoc/accessories/audio/faq.adoc‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
=== Saving AlsaMixer settings
2+
3+
To store the AlsaMixer settings, add the following at the command line:
4+
5+
----
6+
$ sudo alsactl store
7+
----
8+
9+
You can save the current state to a file, then reload that state at startup.
10+
11+
To save:
12+
13+
----
14+
$ sudo alsactl store -f /home/pi/usecase.state
15+
----
16+
17+
To restore a saved file:
18+
19+
----
20+
$ sudo alsactl restore -f /home/pi/usecase.state
21+
----
22+
23+
=== Using external USB devices
24+
25+
If you want to enable 1.2 amp USB support (to allow USB hard disks to power up when
26+
accessory boards are in use), you may also want to add the following line to your `/boot/config.txt`
27+
file:
28+
29+
----
30+
max_usb_current=1
31+
----
32+
33+
34+
=== MPD-based audio with volume control
35+
36+
To allow Music Player Daemon (MPD)-based audio software to control the audio board’s built in volume, the file
37+
`/etc/mpd.conf` may need to be changed to support the correct AlsaMixer name.
38+
39+
This can be achieved by ensuring the 'Audio output' section of `/etc/mpd.conf` has the 'mixer_control'
40+
line. Below is an example for the Texas Instruments-based boards (DAC
41+
PRO/DAC{plus}/DigiAMP{plus}):
42+
43+
----
44+
audio_output {
45+
type "alsa"
46+
name "ALSA Device"
47+
mixer_control "Digital"
48+
}
49+
----
50+
51+
=== Hardware information
52+
53+
* PCB screws are all M2.5.
54+
* PCB standoffs (for case) are 5mm male/female.
55+
* PCB standoffs (for Raspberry Pi to audio boards) are 9mm female/female.
56+
* PCB standoffs (for XLR to DAC PRO) are 8mm female/male.
57+
* PCB standoffs (for the official Raspberry Pi 7-inch display) are 5mm male/female.
58+
* The rotary encoders we have used and tested are the Alpha three-pin rotary encoder
59+
RE160F-40E3-20A-24P, the ALPS EC12E2430804 (RS: 729-5848), and the Bourns ECW0JB24-AC0006L (RS: 263-2839).
60+
* The barrel connector used for powering the DigiAMP{plus} is 2.5mmID, 5.5mmOD, 11mm.
61+
* The DigiAMP{plus} is designed to operate with a 12V to 24V, 3A supply such as the XPPower
62+
VEC65US19 or similar.
63+
* The DigiAMP{plus} uses CamdenBoss two-part connectors. Those fitted to the PCB are
64+
CTBP9350/2AO.
65+
* The speaker terminal used on the Codec Zero will accept wires of between 14~26 AWG
66+
(wire of max 1.6mm in diameter).

0 commit comments

Comments
 (0)