Home / Volumio /

Details of Volumio2 Bluetooth Plugin Modifications

Saturday, September 18, 2021

Volumio

t f B! P L

This page documents, also serving as a personal reference, the modifications made to get the Volumio2 Bluetooth Plugin (where the installation is described) working, focusing on the changes from the previous plugin. This may also serve as reference information when the plugin does not work on different Volumio versions.

Confirming Bluetooth Manager is Active

Plugin-Related Files

The Bluetooth Manager plugin-related files are listed below. The explanation will focus on bluetooth_controller.zip and www3.zip, which were modified. For convenience, file system paths on the machine where the plugin is installed will be used in the explanation.

Installation Script

After the plugin has been installed, the installation script can be found at /data/plugins/audio_interface/bluetooth_controller/install.sh.

volumio@volumio:~$ cat /data/plugins/audio_interface/bluetooth_controller/install.sh
#!/bin/bash
 
echo "Installing Build Enviroment"
sudo cat > /etc/apt/sources.list.d/raspbian.list <<EOC
deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi
EOC
sudo apt-get update
sudo apt-get install -y binutils libtool libstdc++-4.9-dev gcc-4.9 gcc g++-4.9 g++ dpkg-dev
 
echo "Installing Bluetooth Dependencies"
{ echo 'Yes, do as I say!'; yes Y; } | sudo apt-get install autoconf bluez pi-bluetooth bluez-tools libbluetooth-dev libglib2.0-dev libsbc-dev
 
echo "Cloning Bluez-Alsa repo"
cd /tmp
git clone -b v3.1.0 https://github.com/Arkq/bluez-alsa.git
 
echo "Building Bluez-Alsa"
cd bluez-alsa
autoreconf --install
mkdir build && cd build
../configure --disable-hcitop --with-alsaplugindir=/usr/lib/arm-linux-gnueabihf/alsa-lib
make
 
echo "Installing Bluez-Alsa"
sudo make install
 
cat > /lib/systemd/system/bluezalsa.service <<EOC
[Unit]
Description=BluezAlsa proxy
Requires=bluetooth.service
After=bluetooth.service
[Service]
Type=simple
User=root
Group=audio
ExecStart=/usr/bin/bluealsa --a2dp-force-audio-cd
[Install]
WantedBy=multi-user.target
EOC
 
mpd_conf_tmpl='/volumio/app/plugins/music_service/mpd/mpd.conf.tmpl'
sudo mv $mpd_conf_tmpl ${mpd_conf_tmpl}.bak
{ sed -rz 's/(\# bluealsa Output \(begin\) \#+).*(\#+ bluealsa Output \(end\) \#\n)//g' ${mpd_conf_tmpl}.bak; \
cat << EOC
# bluealsa Output (begin) #####################################################
audio_output {
        type "alsa"
        name "bluealsa"
        device "bluealsa"
        mixer_type "software"
}
####################################################### bluealsa Output (end) #
EOC
} > $mpd_conf_tmpl
 
sudo systemctl daemon-reload
sudo systemctl enable bluezalsa.service
 
#requred to end the plugin install
echo "plugininstallend"

Setting Up the Build Environment

Within the installation script, the Bluez-Alsa project is built from source to introduce Bluetooth functionality to Volumio2, which requires setting up a build environment.

According to /etc/apt/sources.list, the Volumio2 software package source is as follows.

volumio@volumio:~$ cat /etc/apt/sources.list
deb http://archive.volumio.org/raspbian/ jessie main contrib non-free rpi
deb-src http://archive.volumio.org/raspbian/ jessie main contrib non-free rpi

However, with only the above source, it was not possible to prepare a build environment that could successfully compile Bluez-Alsa.

Therefore, the original Raspberry Pi software package source was forcibly added to /etc/apt/sources.list.d/raspbian.list. This corresponds to the following part of the installation script.

sudo cat > /etc/apt/sources.list.d/raspbian.list <<EOC
deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi
EOC

Then the following GCC 4.9-related packages are installed.

sudo apt-get update
sudo apt-get install -y binutils libtool libstdc++-4.9-dev gcc-4.9 gcc g++-4.9 g++ dpkg-dev

Additionally, the libraries required for compiling Bluez-Alsa need to be installed as packages. Automatic responses have been configured for prompts that cannot be skipped even with the -y option.

{ echo 'Yes, do as I say!'; yes Y; } | sudo apt-get install autoconf bluez pi-bluetooth bluez-tools libbluetooth-dev libglib2.0-dev libsbc-dev

Volumio2 Bluetooth Plugin installation procedure refers to the above section.


Building and Installing Bluez-Alsa

Once the build environment described above is in place, Bluez-Alsa builds successfully without issues and can be installed.

echo "Cloning Bluez-Alsa repo"
cd /tmp
git clone -b v3.1.0 https://github.com/Arkq/bluez-alsa.git
 
echo "Building Bluez-Alsa"
cd bluez-alsa
autoreconf --install
mkdir build && cd build
../configure --disable-hcitop --with-alsaplugindir=/usr/lib/arm-linux-gnueabihf/alsa-lib
make
 
echo "Installing Bluez-Alsa"
sudo make install

Configuring the bluezalsa Service

The bluezalsa service configuration is written in /lib/systemd/system/bluezalsa.service. The only change from the previous Bluetooth Manager plugin is the following.

    ExecStart=/usr/bin/bluealsa --disable-hfp # Before modification
    ExecStart=/usr/bin/bluealsa --a2dp-force-audio-cd # After modification

Configuring mpd.conf

In the previous Bluetooth Manager plugin, /etc/mpd.conf was rewritten including the Bluetooth MAC address information every time the connected Bluetooth receiver device was changed. Since this was not a desirable approach, it was changed to a method that reflects the settings in the original mpd.conf.tmpl and does not require specifying MAC addresses.

Specifically, the following settings are added to /volumio/app/plugins/music_service/mpd/mpd.conf.tmpl.

audio_output {
        type "alsa"
        name "bluealsa"
        device "bluealsa"
        mixer_type "software"
}

With this configuration, every time the output device settings are updated on the Volumio2 side, they are reflected from this template to /etc/mpd.conf, so the Bluetooth output settings are always maintained.

There are also examples online where, in addition to the above settings, the MAC address of the Bluetooth receiver device is written in ~/.asoundrc. However, it appears that audio is output from the Bluetooth receiver device connected via bluetoothctl without requiring MAC address specification.

Node.js Environment

The Node.js environment for the Bluetooth Manager plugin is deployed in /data/plugins/audio_interface/bluetooth_controller/node_modules. In the previously distributed bluetooth_controller.zip, errors occurred in some Node.js modules making them non-executable, so updates were made to match the latest image environment and bluetooth_controller.zip was recreated.


Identifying Node.js Module Error Locations

If an error is displayed when clicking Enable Plugin on the Bluetooth Manager plugin settings screen, identify the error location with the following command.

$ sudo journalctl -b | less

udev

The udev executable image compatible with the latest Volumio2 environment was missing from the Bluetooth Manager plugin's Node.js environment, causing errors. Fortunately, a usable udev environment existed in Volumio2's own Node.js environment, so it was copied directly under bluetooth_controller.

$ cd /data/plugins/audio_interface/bluetooth_controller/node_modules/udev/
$ cp -rp /volumio/node_modules/udev/build/node-v57-linux-arm .

ptyw.js

ptyw.js was causing a Stack trace error as follows.

 error: Stack trace: Error: The module '/data/plugins/audio_interface/bluetooth_controller/node_modules/ptyw.js/build/Release/pty.node'

Since ptyw.js did not exist in Volumio2's own Node.js environment, it was freshly installed and replaced the ptyw.js folder that was causing the error.

$ npm i ptyw.js
 
> ptyw.js@0.4.1 install /home/volumio/node_modules/ptyw.js
> node-gyp rebuild
 
make: Entering directory '/home/volumio/node_modules/ptyw.js/build'
  CXX(target) Release/obj.target/pty/src/unix/pty.o
  SOLINK_MODULE(target) Release/obj.target/pty.node
  COPY Release/pty.node
make: Leaving directory '/home/volumio/node_modules/ptyw.js/build'
npm WARN saveError ENOENT: no such file or directory, open '/home/volumio/package.json'
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN enoent ENOENT: no such file or directory, open '/home/volumio/package.json'
npm WARN volumio No description
npm WARN volumio No repository field.
npm WARN volumio No README data
npm WARN volumio No license field.
 
+ ptyw.js@0.4.1
added 3 packages in 10.878s
$ cd /data/plugins/audio_interface/bluetooth_controller/node_modules/
$ rm -rf ptyw.js
$ cp -r /home/volumio/node_modules/ptyw.js .

Verifying bluezalsa Service Operation

Once there are no issues with the Node.js environment, the normal startup of the bluezalsa service can be confirmed. It can be verified from the command line as follows.

$  systemctl status bluezalsa
● bluezalsa.service - BluezAlsa proxy
   Loaded: loaded (/lib/systemd/system/bluezalsa.service; enabled)
   Active: active (running) since Mon 2021-09-xx xx:xx:xx UTC; xxs ago
 Main PID: xxx (bluealsa)
   CGroup: /system.slice/bluezalsa.service
           └─xxx /usr/bin/bluealsa --a2dp-force-audio-cd

Modifying index.js

With the change in the /etc/mpd.conf update method, the procedure to directly update /etc/mpd.conf when connecting Bluetooth Devices became unnecessary, so the relevant section was disabled.

    BluetoothController.prototype.onStart = function () {
        // (preceding code omitted)
        // Disabled below
        //self.commandRouter.executeOnPlugin('music_service', 'mpd', 'registerConfigCallback', { type: 'audio_interface', plugin: 'bluetooth_controller', data: 'getMPDConfigString' });
        // (following code omitted)
    }

    BluetoothController.prototype.updateMPD = function () {
        // Disabled below
        /*
        var result = this.commandRouter.executeOnPlugin('music_service', 'mpd', 'createMPDFile', function (error) {
            if (error)
                this.commandRouter.pushToastMessage('Error', error);
        });
        */
    };
}

Volumio3 UI Support (Contemporary Type)

The previous Bluetooth Manager plugin came as a set of bluetooth_controller.zip and ui.zip, and only the Classic type was supported for the UI.

While switching back to Classic for the drag-and-drop installation of bluetooth_controller.zip is acceptable, it would be quite inconvenient on the latest Volumio2 if the parts used in normal operation such as Bluetooth Device selection did not support the Contemporary type. Therefore, www3.zip was newly created to support the Contemporary type. The previous ui.zip was renamed to www.zip.


Areas Requiring Modification

Specifically, without replacing www3.zip, the Bluetooth Devices section (the lower part) of the two parts — Discoverable and Bluetooth Devices — displayed on the Contemporary type plugin → Installed Plugins → Bluetooth Manager → Settings screen will not be shown at all.

The reason is that the template for this page is defined in bluetooth_controller/UIConfig.json. While Discoverable is defined item by item following the plugin display interface, the Bluetooth Devices section calls an external function for batch display. Since the called function needs to be defined in /volumio/http/www3/scripts/app-a79dee18c0.js, the implementation can be extracted from the www-side JavaScript (/volumio/http/www/scripts/app-cc34390d4d.js) and ported to the www3 side.

(The reason the Bluetooth Devices section cannot be described in UIConfig.json like the Discoverable section is that it uses dynamic rendering via Angular.)

$ cat /data/plugins/audio_interface/bluetooth_controller/UIConfig.json
{
    "page": {
        "label": "TRANSLATE.BLUETOOTH_SETTINGS"
    },
    "sections": [
                 { ### Discoverable display area begins here ###
                 "id": "port",
                 "element": "section",
                 "label": "TRANSLATE.DISCOVERABLE",
                 "icon": "fa-bluetooth",
                 "onSave": {"type":"controller", "endpoint":"audio_interface/bluetooth_controller", "method":"saveOptions"},
                 "saveButton": {
                 "label": "TRANSLATE.SAVE",
                 "data": [
                          "discoverable_setting"
                          ]
                 },
                 "content": [
                             {
                             "id": "discoverable_setting",
                             "element": "switch",
                             "label": "TRANSLATE.DISCOVERABLE",
                             "doc": "TRANSLATE.DISCOVERABLE_DOC",
                             "value": false
                             }
                             ]
                 }, ### Discoverable display area ends here ###
                 ### Bluetooth Device display area begins here ###
                 {"coreSection":"bluetooth"}
                 ### Bluetooth Device display area ends here ###
                ]
}

UI JavaScript Modifications

However, as can be seen by looking at /volumio/http/www/scripts/app-cc34390d4d.js and /volumio/http/www3/scripts/app-a79dee18c0.js, they are minified, so it is not straightforward. While using de-minification tools, the Bluetooth Manager-related code was carefully extracted from /volumio/http/www/scripts/app-cc34390d4d.js and ported to /volumio/http/www3/scripts/app-a79dee18c0.js.

Only the key points are listed below.

  • Extract e.put("app/plugin/core-plugin/bluetooth-plugin.html", ...), from www/scripts/app-cc34390d4d.js and add it to www3/scripts/app-a79dee18c0.js
  • Add om=i(141),sm=a(om) to the end of the function definition section at the beginning of www3/scripts/app-a79dee18c0.js, and add .controller("BluetoothPluginController", sm["default"]) in the initialization section
  • Extract the function (e, t) {"use strict"; ... } section containing "bluetooth" from www/scripts/app-cc34390d4d.js and add it at the end (141st entry) of the function array definition section in www3/scripts/app-a79dee18c0.js

CSS and i18n Modifications

The following changes are also made to CSS and i18n.

  • Extract phrases starting with #bluetoothPlugin {} from www/styles/app-b84007a5bf.css, excluding other items like #wifiPlugin, and add them to www3/styles/app-936d2e26fe.css
  • Add the following to /volumio/http/www3/app/i18n/locale-en.json
    "BLUETOOTH": {
        "AUDIO":"Audio Device",
        "COMPUTER":"Computer",
        "CONNECT":"Connect",
        "DISCONNECT":"Disconnect",
        "REFRESH":"Refresh"
    }

With this, the Bluetooth Devices section of Bluetooth Manager is now dynamically displayed in the Contemporary type UI just as it is in the Classic type.

Settings, Commands, and Tools

The commands and tools used for the plugin modifications are listed below.

Settings

  • bluezalsa service configuration: /lib/systemd/system/bluezalsa.service
  • MPD configuration: /etc/mpd.conf
  • MPD template: /volumio/app/plugins/music_service/mpd/mpd.conf.tmpl
  • asound.conf configuration: /etc/asound.conf, ~/.asoundrc (neither was used this time)

Commands

### Restart bluealsa ###
$ sudo systemctl daemon-reload
$ sudo systemctl enable bluezalsa.service
$ sudo reboot
 
### Check bluezalsa status ###
systemctl status bluezalsa
 
### Restart mpd ###
$ sudo systemctl restart mpd.service
 
### Bluetooth configuration ###
$ bluetoothctl
[bluetooth]# power on
[bluetooth]# scan on
[bluetooth]# pair <device MAC>
[bluetooth]# trust <device MAC>
[bluetooth]# connect <device MAC>
[bluetooth]# info <device MAC>
 
### List sound devices ###
$ aplay -L
 
### ALSAMIXER ###
$ alsamixer
$ alsamixer -D bluealsa
 
### Check bluealsa information ###
$ amixer -D bluealsa
 
### Volume configuration ###
$ amixer -c 5 -M set "SoftMaster" unmute 50%  # Device number 5 may vary
$ amixer -D bluealsa -M set "[Device Name] - A2DP" unmute 50%
 
### Overall operation check including plugin ###
$ sudo journalctl -b | less
 
 
### Minify ####
## for JavaScript ##
$ sudo npm install -g uglify-js
$ uglifyjs --compress --mangle -- xxx.js
 
## for CSS ##
$ sudo npm install -g clean-css-cli
$ cleancss xxx.css

Tools

Reference URLs

About Me

My photo
Electronics, programming & audio

Featured Post

Synchronizing Radio-Controlled Clocks with Raspberry Pi Pico W (JJY Standard Radio Wave Emulator)

As a Raspberry Pi Pico W application, I built a JJY emulator for radio-controlled clocks (for time synchronization) with minimal peripheral...

QooQ