Push to production

documentation/asciidoc/accessories/audio.adoc

@@ -0,0 +1,19 @@
+
+include::audio/introduction.adoc[]
+
+include::audio/dac_pro.adoc[]
+
+include::audio/dac_plus.adoc[]
+
+include::audio/digiamp_plus.adoc[]
+
+include::audio/codec_zero.adoc[]
+
+include::audio/configuration.adoc[]
+
+include::audio/getting_started.adoc[]
+
+include::audio/advanced.adoc[]
+
+include::audio/faq.adoc[]
+

documentation/asciidoc/accessories/audio/advanced.adoc

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

documentation/asciidoc/accessories/audio/codec_zero.adoc

@@ -0,0 +1,32 @@
+=== Raspberry Pi Codec Zero
+
+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.
+
+* High performance 24-bit audio codec
+* Supports common audio sample rates between 8-96kHz
+* Built in micro-electro-mechanical (MEMS) microphone (Mic2)
+* Mono electret microphone (Mic2 left)
+* Automatic MEMS disabling on Mic2 insert detect
+* Supports additional (no fit) mono electret microphone (Mic1 right)
+* Stereo auxiliary input channel (AUX IN) - PHONO/RCA connectors
+* Stereo auxiliary output channel (Headphone/AUX OUT)
+* Flexible analogue and digital mixing paths
+* Digital signal processors (DSP) for  automatic level control (ALC)
+* Five-band EQ 
+* Mono line-out/mini speaker driver: 1.2W @ 5V, THD<10%, R=8Ω
+
+image::images/Codec_Zero_Board_Diagram.jpg[width="80%"]
+
+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Ω).
+
+In addition to the green (GPIO23) and red (GPIO24) LEDs, a tactile programmable button (GPIO27) is also provided.
+
+==== Pinouts
+[cols="1,12"]
+|===
+| *P1/2* | Support external PHONO/RCA sockets if needed. P1: AUX IN, P2: AUX OUT.
+| *P1* | Pin 1 is square.
+|===
+image::images/CODEC_ZERO_ZOOMED_IN_DIAGRAM.jpg[width="50%"]
+
+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

@@ -0,0 +1,161 @@
+== Configuration
+
+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:
+
+image::images/gui.png[]
+
+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.
+
+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:
+
+----
+$ sudo nano /boot/config.txt
+----
+
+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:
+
+----
+#dtparam=audio=on
+----
+
+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.
+
+----
+$ sudo reboot
+----
+
+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.
+
+=== Attaching the HAT
+
+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.
+
+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.
+
+=== Codec Zero configuration
+
+The Raspberry Pi Codec Zero board uses the Dialog Semiconductor DA7212 codec. This allows
+the recording of audio from the built-in MEMS microphone, from stereo phono sockets (AUX
+IN) or two mono external electret microphones. Playback is through stereo phono sockets (AUX OUT)
+or a mono speaker connector.
+
+Each input and output device has its own mixer, allowing the audio levels and volume to be adjusted
+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.
+
+Both the AUX IN and AUX OUT are 1V RMS. It may be necessary to adjust
+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.
+
+Preconfigured scripts (loadable ALSA settings) https://github.com/iqaudio/Pi-Codec[are available on GitHub], offering:
+
+* Mono MEMS mic recording, mono speaker playback
+* Mono MEMS mic recording, mono AUX OUT playback
+* Stereo AUX IN recording, stereo AUX OUT playback
+* Stereo MIC1/MIC2 recording, stereo AUX OUT playback
+
+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:
+
+----
+$ git clone https://github.com/iqaudio/Pi-Codec.git
+----
+
+If git is not installed, run the following command to install it:
+
+----
+$ sudo apt install git
+----
+
+The following command will set your device to use the on-board MEMS microphone and output for speaker playback:
+
+----
+$ sudo alsactl restore -f /home/pi/Pi-Codec/IQaudIO_Codec_OnboardMIC_record_and_SPK_playback.state
+----
+
+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:
+
+----
+$ sudo nano /etc/rc.local
+----
+
+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:
+
+----
+#!/bin/sh -e
+#
+# rc.local
+#
+# This script is executed at the end of each multiuser runlevel.
+# Make sure that the script will "exit 0" on success or any other
+# value on error.
+#
+# In order to enable or disable this script just change the execution
+# bits.
+#
+# By default this script does nothing.
+
+sudo alsactl restore -f /home/pi/Pi-Codec/IQaudIO_Codec_OnboardMIC_record_and_SPK_playback.state
+
+exit 0
+----
+
+Ctrl X, Y and Enter to save and reboot your device for the settings to take effect:
+
+----
+$ sudo reboot
+----
+
+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:
+
+----
+$ sudo nano ./asoundrc
+----
+
+Add the following to the file:
+
+----
+pcm.!default {
+        type hw
+        card Zero
+}
+----
+
+Ctrl X, Y and Enter to save, and reboot once more to complete the configuration:
+
+----
+$ sudo reboot
+----
+
+=== Muting and unmuting the DigiAMP{plus}
+
+The DigiAMP{plus} mute state is toggled by GPIO22 on Raspberry Pi. The latest audio device tree
+supports the unmute of the DigiAMP{plus} through additional parameters.
+
+Firstly a "one-shot" unmute when kernel module loads.
+
+----
+dtoverlay=iqaudio-dacplus,unmute_amp
+----
+
+Unmute the amp when an ALSA device is opened by a client. Mute, with a five-second delay
+when the ALSA device is closed. (Reopening the device within the five-second close
+window will cancel mute.)
+
+----
+dtoverlay=iqaudio-dacplus,auto_mute_amp
+----
+
+If you do not want to control the mute state through the device tree, you can also script your own
+solution. 
+
+The amp will start up muted. To unmute the amp:
+
+----
+$ sudo sh -c "echo 22 > /sys/class/gpio/export"
+$ sudo sh -c "echo out >/sys/class/gpio/gpio22/direction"
+$ sudo sh -c "echo 1 >/sys/class/gpio/gpio22/value"
+----
+
+to mute the amp once more:
+
+----
+$ sudo sh -c "echo 0 >/sys/class/gpio/gpio22/value"
+----

documentation/asciidoc/accessories/audio/dac_plus.adoc

@@ -0,0 +1,15 @@
+=== Raspberry Pi DAC{plus}
+
+Raspberry Pi DAC{plus} is a high-resolution audio output HAT that provides 24-bit 192kHz digital audio output.
+
+image::images/DAC+_Board_Diagram.jpg[width="80%"]
+
+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.
+
+==== Pinouts
+[cols="1,12"]
+|===
+| *P1* | Analogue out (0-2V RMS), carries GPIO27, MUTE signal (headphone detect), left and right
+audio and left and right ground.
+| *P6* | Headphone socket signals (pin1: LEFT, 2:GROUND, 3: RIGHT, 4:GROUND, 5:DETECT).
+|===

documentation/asciidoc/accessories/audio/dac_pro.adoc

@@ -0,0 +1,21 @@
+=== Raspberry Pi DAC Pro
+
+The Raspberry Pi DAC Pro HAT is our highest-fidelity digital to analogue converter (DAC).
+
+image::images/DAC_Pro_Board_Diagram.jpg[width="80%"]
+
+With the Texas Instruments PCM5242, the DAC Pro provides outstanding signal-to-noise ratio (SNR)
+and supports balanced/differential output in parallel to phono/RCA line-level output. It also includes a
+dedicated headphone amplifier. The DAC Pro is powered by a Raspberry Pi through the GPIO header.
+
+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.
+
+==== Pinouts
+[cols="1,12"]
+|===
+| *P1* | Analogue out (0-2V RMS), carries GPIO27, MUTE signal (headphone detect), left and right
+audio and left and right ground.
+| *P6* | Headphone socket signals (1: LEFT, 2: GROUND, 3: RIGHT, 4: GROUND, 5: DETECT).
+| *P7/9* | Differential (0-4V RMS) output (P7: LEFT, P9: RIGHT).
+| *P10* | Alternative 5V input, powering Raspberry Pi in parallel.
+|===

documentation/asciidoc/accessories/audio/digiamp_plus.adoc

@@ -0,0 +1,22 @@
+=== Raspberry Pi DigiAMP{plus}
+
+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.
+
+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).
+
+image::images/DigiAMP+_Board_Diagram.jpg[width="80%"]
+
+DigiAMP{plus}’s power in barrel connector is 5.5mm x 2.5mm. 
+
+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).
+
+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.
+
+WARNING: Do not apply power to the Raspberry Pi's own power input when using DigiAMP{plus}.
+
+==== Pinouts 
+[cols="1,12"]
+|===
+| *P5* | Alternative power input for hard wired installations (polarity must be observed).
+| *P8* | TAS5756m Internal GPIO1/2/3
+|===

documentation/asciidoc/accessories/audio/faq.adoc

@@ -0,0 +1,66 @@
+=== Saving AlsaMixer settings
+
+To store the AlsaMixer settings, add the following at the command line:
+
+----
+$ sudo alsactl store
+----
+
+You can save the current state to a file, then reload that state at startup.
+
+To save:
+
+----
+$ sudo alsactl store -f /home/pi/usecase.state
+----
+
+To restore a saved file:
+
+----
+$ sudo alsactl restore -f /home/pi/usecase.state
+----
+
+=== Using external USB devices
+
+If you want to enable 1.2 amp USB support (to allow USB hard disks to power up when
+accessory boards are in use), you may also want to add the following line to your `/boot/config.txt`
+file:
+
+----
+max_usb_current=1
+----
+
+
+=== MPD-based audio with volume control
+
+To allow Music Player Daemon (MPD)-based audio software to control the audio board’s built in volume, the file
+`/etc/mpd.conf` may need to be changed to support the correct AlsaMixer name.
+
+This can be achieved by ensuring the 'Audio output' section of `/etc/mpd.conf` has the 'mixer_control'
+line. Below is an example for the Texas Instruments-based boards (DAC
+PRO/DAC{plus}/DigiAMP{plus}):
+
+----
+audio_output {
+    type "alsa"
+    name "ALSA Device"
+    mixer_control "Digital"
+}
+----
+
+=== Hardware information
+
+* PCB screws are all M2.5.
+* PCB standoffs (for case) are 5mm male/female.
+* PCB standoffs (for Raspberry Pi to audio boards) are 9mm female/female.
+* PCB standoffs (for XLR to DAC PRO) are 8mm female/male.
+* PCB standoffs (for the official Raspberry Pi 7-inch display) are 5mm male/female.
+* The rotary encoders we have used and tested are the Alpha three-pin rotary encoder
+RE160F-40E3-20A-24P, the ALPS EC12E2430804 (RS: 729-5848), and the Bourns ECW0JB24-AC0006L (RS: 263-2839).
+* The barrel connector used for powering the DigiAMP{plus} is 2.5mmID, 5.5mmOD, 11mm.
+* The DigiAMP{plus} is designed to operate with a 12V to 24V, 3A supply such as the XPPower
+VEC65US19 or similar.
+* The DigiAMP{plus} uses CamdenBoss two-part connectors. Those fitted to the PCB are 
+CTBP9350/2AO.
+* The speaker terminal used on the Codec Zero will accept wires of between 14~26 AWG
+(wire of max 1.6mm in diameter).