Installation Guide

MLSC

This installation guide will help you install your own MLSC on your Raspberry Pi.

Advanced users can check out the tutorial video I created for the manual installation:

The installation script setup.sh simplifies the process shown in the video.

Overview

Scheme_03

1. Install Server

Install MLSC

Preconditions

Installation was tested on a fresh image of "Raspberry Pi OS Lite" 2021 11th January with the Kernel version 5.4. The hostname and password were changed and SSH was activated to connect in headless mode.

Automatic Setup Script

Run the following command in your terminal:

curl -sSL https://raw.githubusercontent.com/TobKra96/music_led_strip_control/master/setup.sh | sudo bash -s -- -b master

After the installation was successful, continue with the following steps: Configure Music LED Strip Control

Configure Music LED Strip Control

At this stage, MLSC and all dependencies should be installed. Now we can execute the program and configure the main settings. Navigate to the server directory:

cd /share/music_led_strip_control/server

Run the program manually:

sudo python3 main.py

You will get a terminal output like this:

The error in the screenshot is caused by the missing microphone config:

INFO     - libs.audio_process_service     - Found the following audio sources:
INFO     - libs.audio_process_service     - 1 - USB PnP Sound Device: Audio (hw:1,0) - 44100.0
INFO     - libs.audio_process_service     - 2 - default - 44100.0
ERROR    - libs.audio_process_service     - ********************************************************
ERROR    - libs.audio_process_service     - *                      Error                           *
ERROR    - libs.audio_process_service     - ********************************************************
ERROR    - libs.audio_process_service     - Could not find the mic with the id: 0
ERROR    - libs.audio_process_service     - Using the first mic as fallback.
ERROR    - libs.audio_process_service     - Please change the id of the mic inside the config.
INFO     - libs.audio_process_service     - Selected ID: 1
INFO     - libs.audio_process_service     - Using 1 - USB PnP Sound Device: Audio (hw:1,0) - 44100.0
INFO     - libs.device                    - Starting device: Raspberry Pi

The output means that MLSC found two audio inputs with the IDs 1 and 2. 1 is the USB Audio Device and 2 is the default audio device.

Keep the program running and open a web browser on a device on the same local network.

Enter the following into the search bar:

http://<IP_OF_RASPBERRY_PI>:8080

Replace <IP_OF_RASPBERRY_PI> with the IP or hostname of the Raspberry Pi.

Note: raspberrypi.local:8080 should also work.

Make sure the port is set to the default port: 8080

The Dashboard should appear. Select General Settings in the navigation sidebar:

Now you should see the General Settings with Audio Device and Default Sample Rate.

In the Audio Device dropdown select the applicable device option.

In the Default Sample Rate write the matching entry that was in the console output: 44100.

Press the "Save" button on the bottom of the General Settings page. The changes should be applied.

Restart MLSC:

Press CTRL+C and restart main.py:

sudo python3 main.py

The error should disappear and MLSC automatically will use the selected input device.

2. Install Client/Output

i. Local Raspberry Pi for Output

Scheme_03

Wiring

The LED Strip, the Power Supply for the LED Strip, and the Raspberry Pi have to share the same GND. This is important for the signal. Connect all three ground connections together (Black wire in the scheme). The signal data cable will be connected between the Raspberry PI and the LED Strip. Use a resistor or potentiometer to reduce the Signal Ringing (see Wikipedia Signal Ringing). The resistor value depends on the cable quality and the signal cable length. It can be between 120 Ohm and 220 Ohm.

I would recommend using a potentiometer and adjust the resistance directly.

Raspberry Pi Pinout

Here is the pinout of the Raspberry Pi:

Pinout_RaspberryPi

Use any Ground Pin for the ground cable.

Pin 12 (GPIO 18): Data Pin for the data cable.

Add output in MLSC

Start MLSC and open the web interface:

http://<IP_OF_RASPBERRY_PI>:8080

Replace <IP_OF_RASPBERRY_PI> with the IP or hostname of the Raspberry Pi.

Make sure the port is set to the default port: 8080

Go to Device Settings:

Create a new device:

Now change the following inputs according to your needs:

Switch to the previously created device. It should appear as "Default Device".
Enter a name for the device.
Set the max FPS. Higher FPS causes higher CPU usage. Using 60 FPS is recommended.
Enter the LED count.
Define the middle of the LED Strip. If you use your LED strip around a corner, you can enter the number of LEDs before the corner.
Set "Output Raspberry Pi" as "Selected Output Type".
Adjust the brightness of the LEDs.
The GPIO Data Pin. Use GPIO 18.
Save the changes.

Now you can go back to the Dashboard and select an effect. The LED strip should turn on.

Limitations

MLSC uses the rpi_ws281x library for the output signal. We are using the PWM for signal generation. If your LED strip only flickers or does not set the LED colors as expected, check the resistance of the potentiometer or resistor. Another solution could be:

Since this library and the onboard Raspberry Pi audio both use the PWM, they cannot be used together. You will need to blacklist the Broadcom audio kernel module by creating a file /etc/modprobe.d/snd-blacklist.conf with the following inside:

blacklist snd_bcm2835

If the audio device is still loading after blacklisting, you may also need to comment it out in the /etc/modules file.

On headless systems you may also need to force audio through HDMI. Edit config.txt and add:

hdmi_force_hotplug=1
hdmi_force_edid_audio=1

A reboot is required for this change to take effect.

Some distributions use audio by default, even if nothing is being played. If audio is required, you can use a USB audio device instead.

Example with a WS2815 LED Strip

Raspberry Pi 4
WS2815 144 LED/m 12V
12V 10A Power Supply. Minimum required current: 144 LEDs * 15mA = 2,16A --> 5A is the next common 12V power supply.
Potentiometer 0-2k Ohm
TONOR Conference Microphone. You can use any Linux compatible USB Microphone or USB Soundcard with a connected microphone.

RaspberryPiExample~2

ESP8266 Client

Use an ESP8266 as a client. The Raspberry Pi will work as a server.

Scheme_04

Concept

For the Server and Client Architecture, we will create our own WiFi Access Point on the Raspberry Pi. This LED Wifi Network will be used for the LED Output data, which will be received by the ESP8266 clients. The Web Interface can be accessed on the default Home Network via Ethernet (LAN Port with cable).

Scheme_05

Setup the Raspberry Pi

We start with the installation of the Access point. It contains hostapd (the Access Point Software), dnsmasq (the DNS Server/Cache and DHCP Server) and dhcpcd (the DHCP Client).

Update packages:

sudo apt-get update
sudo apt-get upgrade

Install required packages:

sudo apt install dnsmasq hostapd

Configure the packages:

If your wifi is already configured with a network, please delete the network config:

In the terminal type: sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
Delete the relevant wifi network block (including the ‘network=’ and opening/closing braces.
Press ctrl-x followed by ‘y’ and enter to save the file.
You’re done!

We start with the DHCP settings.

Open/create the following file:

sudo nano /etc/dhcpcd.conf

Paste the following content to the end of the file:

interface wlan0
static ip_address=172.24.26.1/24

You can choose your own static IP address.

It should look like this:

In this file, we set the static IP address of the interface wlan0.

In Nano, you can save changes by pressing Ctrl+X, "Y" and "Enter".

Restart the DHCP Client Service:

sudo systemctl restart dhcpcd

We want to check if the wlan0 interface is available. Enter the following command:

ip l

You should see something like this:

Now we continue with the DNS Server. Backup the current configuration:

sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.bak

Create a new config file:

sudo nano /etc/dnsmasq.conf

Enter the following lines:

# Activate the DHCP-Server for the Wifi-Interface
interface=wlan0

# DHCP-Server not active for Ethernet Network
no-dhcp-interface=eth0

# IPv4 Address Scope and Lease-Time
dhcp-range=172.24.26.0,172.24.26.255,255.255.255.0,24h

# DNS
dhcp-option=option:dns-server,172.24.26.1

Change the IP address if needed. Ensure it matches with the static IP you set before.

You can check the config with:

dnsmasq --test -C /etc/dnsmasq.conf

It should return "dnsmasq: syntax check OK."

Restart DNSMASQ:

sudo systemctl restart dnsmasq

Show the status of dnsmasq:

sudo systemctl status dnsmasq

We will see something like this:

It will be active and there should be no errors.

Enable the service to start on reboot:

sudo systemctl enable dnsmasq

Now we can configure the access point software.

Create a new config file:

sudo nano /etc/hostapd/hostapd.conf

Enter the following settings:

# Interface and driver
interface=wlan0
#driver=nl80211

# Wifi Configuration
ssid=MLSC-Wifi
channel=1
hw_mode=g
ieee80211n=1
ieee80211d=1
country_code=DE
wmm_enabled=1

# Wifi Encryption
auth_algs=1
wpa=2
wpa_key_mgmt=WPA-PSK
rsn_pairwise=CCMP
wpa_passphrase=wifipassword

You have to change country_code with your own country code.

Change the Wifi channel if the network performance is low.

Change the password in wpa_passphrase

Change the file rights. Only the admin should see the wifi password:

sudo chmod 600 /etc/hostapd/hostapd.conf

Check if the configuration worked:

sudo hostapd -dd /etc/hostapd/hostapd.conf

You can stop it with Ctrl+C.

If hostapd won't start, you can try to unblock the WiFi and start hostapd again:

sudo rfkill unblock all
sudo hostapd -dd /etc/hostapd/hostapd.conf

Add hostapd to the autostart:

sudo nano /etc/default/hostapd

Add the following parameters:

RUN_DAEMON=yes
DAEMON_CONF="/etc/hostapd/hostapd.conf"

Start hostapd and check the status:

sudo systemctl unmask hostapd
sudo systemctl start hostapd
sudo systemctl enable hostapd
sudo systemctl status hostapd

The service should be active (running).

Restart the system and check if everything works:

sudo reboot

Setup ESP8266

Flash the firmware.

Arduino IDE was used for flashing the firmware. Ensure you have installed the right board packages.

My Boardmanager URL is:

https://dl.espressif.com/dl/package_esp32_index.json,http://arduino.esp8266.com/stable/package_esp8266com_index.json

You can add this to the "Files/Preferences" Menu. Install the ESP Board Package inside the Board Manager and configure the Serial connections. This setting depends on your ESP Microcontroller you are using.

In my case it's a NodeMCU with the following settings:

Now we have to install the required libraries. Use the library manager for it:

ESP8266WiFi
WiFiUdp
NeoPixelBus

(NeoPixelBus by Makuna)

Open the following file:

music_led_strip_control/client/udp/esp/nodemcu_client/nodemcu_client.ino

Modify the following variables:

NUM_LEDS Number of LEDs you are using.
ssid The Wifi SSID of your Access Point.
password The password of your Access Point.
ip The IP, that the ESP will use.
gateway The Gateway IP of your Raspberry Pi. This should be the static IP you set before.
subnet The Subnet Mask that your Access Point uses.

Now you can build the program and flash it to the ESP:

The LED of the ESP should blink during the Upload Process and the console of the Arduino IDE should show this:

Now we can start with the wiring:

Scheme_06

Pinout

Pinout_ESP

Use a Ground Pin to share the same Ground with LED Strip and Power supply.

Use the GPIO 3 Pin (RX) for the Data Signal cable.

Setup MLSC

Start MLSC and open the web interface:

http://<IP_OF_RASPBERRY_PI>:8080

Replace <IP_OF_RASPBERRY_PI> with the IP or hostname of the Raspberry Pi.

Make sure the port is set to the default port: 8080

Go to the Device Settings:

Add a new device with the following settings:

Switch to the newly created device. It should appear as "Default Device".
Enter a name for the device.
Set the max FPS. Higher FPS causes higher CPU usage. Using 60 FPS is recommended.
Enter the LED count.
Define the mid of the LED Strip. If you use your LED strip around a corner, you can enter the number of LEDs before the corner.
Set "Output Network via UDP" as "Selected Output Type".
Set the IP Address of the ESP.
The port of the UDP connection. 7777 is the default setting.
Save the changes.

Now you can turn on the LED Strip and check if the Network Connection and the LED strip works.

Error Handling

There are multiple logging mechanisms implemented. The ESP Led Strip shows an LED Code during the connection phase.
LED 1: Connecting - The LED Strip tries to connect. The LED will blink.
LED 2: Reconnected - Indicates if the LED Strip reconnected to the local network.
LED 3: WL_CONNECTED - ESP connected to the WiFi Network.
LED 4: WL_NO_SHIELD - Could not find a WiFi shield.
LED 5: WL_IDLE_STATUS - The WiFi is in the idle state.
LED 6: WL_NO_SSID_AVAIL - Could not find the Wifi with the configured SSID.
LED 7: WL_SCAN_COMPLETED - Network scan completed.
LED 8: WL_CONNECTED - Connected to the WiFi.
LED 9: WL_CONNECT_FAILED - The connection failed.
LED 10: WL_CONNECTION_LOST - The connection to the WiFi network was lost.
LED 11: WL_DISCONNECTED - The ESP disconnected from the local network.

Additionally, you can monitor the serial output of the ESP. It will show you the current state. There is a hardware limitation of the maximum amount of clients that could connect to the raspberry pi. On the Raspberry Pi 4 it's ~8 clients. The Raspberry Pi 3b+ supports ~20. You can use a USB WiFi Dongle with the RT5370 Chipset to increase the limit to 100+.