Installation Guide

Whether you're a tech enthusiast or just getting started, we'll walk you through every step of the process.

Prerequisites

Unless receiving power through a Linux computer, running Nocturne on your Car Thing requires a host device such as a Raspberry Pi, a microSD card, a microUSB to USB-C cable, a microUSB/your power source's connector, as well as a Spotify Premium account. You will also need superbird-tool to flash the image regardless of your computer's operating system.

Installation

Installing Nocturne differs slightly depending on your operating system.

Windows

Raspberry Pi Setup

Download and open Raspberry Pi Imager, select Raspberry Pi OS (Legacy, 64-bit) Lite, select "Edit Settings", check "Set hostname", check "Set username and password" (set a password), check "Configure wireless LAN", (enter your network's SSID and password), check "Set local settings". Open the Services tab, enable SSH, and use password authentication. Write the configured OS to your microSD card and insert it into your Raspberry Pi.

Flashing Process

If you haven't already, download superbird-tool and run the setup process detailed here.

Download and unzip the latest image from Releases, connect Car Thing to your computer in USB Mode (hold preset buttons 1 and 4 while connecting), and run the following from your command line:

# Go into the superbird-tool repository
$ cd C:\path\to\superbird-tool-main

# Find device
$ python superbird_tool.py --find_device

# Flash Nocturne image, without resetting the data partition 
$ python superbird_tool.py --dont_reset --restore_device C:\path\to\nocturne-image\image

After the flashing completes, connect your Raspberry Pi to your computer, and change directories to the scripts folder.

# Go into the setup-scripts folder
$ cd \path\to\nocturne-image\setup-scripts

There are two different ways to use Nocturne. You can either use it at your desk, or in your car.

Using Nocturne at your desk (Windows)

Connect your Car Thing to the Raspberry Pi and run the following from your command line:

# Transfer setup_host_rpi.sh to Raspberry Pi
$ scp \path\to\nocturne-image\setup-scripts\setup_host_rpi.sh [email protected]:/home/pi/

# SSH into Raspberry Pi
$ ssh [email protected]

# Make setup_host_rpi.sh executable
$ chmod +x /home/pi/setup_host_rpi.sh

# Execute setup_host_rpi.sh
$ sudo ./setup_host_rpi.sh

# Reboot Raspberry Pi
$ sudo reboot

Using Nocturne in your car (Windows)

Connect your Car Thing to the Raspberry Pi and run the following from your command line:

# Transfer setup_host_rpi.sh to Raspberry Pi
$ scp \path\to\nocturne-image\setup-scripts\setup_host_rpi.sh [email protected]:/home/pi/

# SSH into Raspberry Pi
$ ssh [email protected]

# Make setup_host_rpi.sh executable
$ chmod +x /home/pi/setup_host_rpi.sh

# Execute setup_host_rpi.sh
$ sudo ./setup_host_rpi.sh

# Reboot Raspberry Pi
$ sudo reboot

For car usage, you will also need to run the setup_hotspot.py script:

# Transfer setup_hotspot.py to Raspberry Pi
$ scp \path\to\nocturne-image\setup-scripts\setup_hotspot.py [email protected]:/home/pi/

# SSH into Raspberry Pi
$ ssh [email protected]

# Execute setup_hotspot.py
$ sudo python3 ./setup_hotspot.py

The script will ask you to input the name of your hotspot, as well as the password for the hotspot. After the script completes, Nocturne is almost ready to be used in your car!

macOS

Raspberry Pi Setup

Download and open Raspberry Pi Imager, select Raspberry Pi OS (Legacy, 64-bit) Lite, select "Edit Settings", check "Set hostname", check "Set username and password" (set a password), check "Configure wireless LAN", (enter your network's SSID and password), check "Set local settings". Open the Services tab, enable SSH, and use password authentication. Write the configured OS to your microSD card and insert it into your Raspberry Pi.

Flashing Process

If you haven't already, download superbird-tool and run the setup process detailed here.

Download and unzip the latest image from Releases, connect Car Thing to your computer in USB Mode (hold preset buttons 1 and 4 while connecting), and run the following from your command line:

# Go into the superbird-tool repository
$ cd /path/to/superbird-tool-main

# Find device
$ /opt/homebrew/bin/python3 superbird_tool.py --find_device

# Flash Nocturne image, without resetting the data partition 
$ /opt/homebrew/bin/python3 superbird_tool.py --dont_reset --restore_device /path/to/nocturne-image/image

After the flashing completes, connect your Raspberry Pi to your computer, and change directories to the scripts folder:

# Go into the setup-scripts folder
$ cd /path/to/nocturne-image/setup-scripts

Using Nocturne at your desk (macOS)

Connect your Car Thing to the Raspberry Pi and run the following from your command line:

# Transfer setup_host_rpi.sh to Raspberry Pi
$ scp /path/to/nocturne-image/setup-scripts/setup_host_rpi.sh [email protected]:/home/pi/

# SSH into Raspberry Pi
$ ssh [email protected]

# Make setup_host_rpi.sh executable
$ chmod +x /home/pi/setup_host_rpi.sh

# Execute setup_host_rpi.sh
$ sudo ./setup_host_rpi.sh

# Reboot Raspberry Pi
$ sudo reboot

Using Nocturne in your car (macOS)

Connect your Car Thing to the Raspberry Pi and run the following from your command line:

# Transfer setup_host_rpi.sh to Raspberry Pi
$ scp /path/to/nocturne-image/setup-scripts/setup_host_rpi.sh [email protected]:/home/pi/

# SSH into Raspberry Pi
$ ssh [email protected]

# Make setup_host_rpi.sh executable
$ chmod +x /home/pi/setup_host_rpi.sh

# Execute setup_host_rpi.sh
$ sudo ./setup_host_rpi.sh

# Reboot Raspberry Pi
$ sudo reboot

For car usage on macOS, you will also need to run the setup_hotspot.py script:

# Transfer setup_hotspot.py to Raspberry Pi
$ scp /path/to/nocturne-image/setup-scripts/setup_hotspot.py [email protected]:/home/pi/

# SSH into Raspberry Pi
$ ssh [email protected]

# Execute setup_hotspot.py
$ sudo python3 ./setup_hotspot.py

Linux

A Raspberry Pi is not required on Linux, unless you want to use Nocturne in your car.

Raspberry Pi Setup

Download and open Raspberry Pi Imager, select Raspberry Pi OS (Legacy, 64-bit) Lite, select "Edit Settings", check "Set hostname", check "Set username and password" (set a password), check "Configure wireless LAN", (enter your network's SSID and password), check "Set local settings". Open the Services tab, enable SSH, and use password authentication. Write the configured OS to your microSD card and insert it into your Raspberry Pi.

Flashing Process

If you haven't already, download superbird-tool and run the setup process detailed here.

Download and unzip the latest image from Releases, connect Car Thing to your computer in USB Mode (hold preset buttons 1 and 4 while connecting), and run the following from your command line:

# Go into the superbird-tool repository
$ cd /path/to/superbird-tool-main

# Find device
$ sudo python3 ./superbird_tool.py --find_device

# Flash Nocturne image, without resetting the data partition 
$ sudo python3 ./superbird_tool.py --dont_reset --restore_device /path/to/nocturne-image/image

After the flashing completes, unplug and replug your Car Thing, and change directories to the scripts folder:

# Go into the setup-scripts folder
$ cd /path/to/nocturne-image/setup-scripts

Using Nocturne at your desk (Linux)

At this point, there are two different scripts that you can use. The first one, setup_host_apt.sh, is used on Linux distros that utilize apt as it's package manager. The second one, setup_host_pacman.sh, is used on Linux distros that utilize Pacman as it's package manager. If you use Pacman, replacesetup_host_apt.sh in the following commands withsetup_host_pacman.sh to continue with setup.

It is important to note that setup_host_pacman.sh has not been tested very well, so it may not work as intended for setup.

# Make setup_host_apt.sh executable
$ chmod +x setup_host_apt.sh

# Execute setup_host_apt.sh
$ sudo ./setup_host_apt.sh

Using Nocturne in your car (Linux)

To use Nocturne in your car, you will need to have a Raspberry Pi to provide network.

Connect your Raspberry Pi to your computer, your Car Thing to the Raspberry Pi, and run the following from your command line:

# Transfer setup_host_rpi.sh to Raspberry Pi
$ scp /path/to/nocturne-image/setup-scripts/setup_host_rpi.sh [email protected]:/home/pi/

# SSH into Raspberry Pi
$ ssh [email protected]

# Make setup_host_rpi.sh executable
$ chmod +x /home/pi/setup_host_rpi.sh

# Execute setup_host_rpi.sh
$ sudo ./setup_host_rpi.sh

# Reboot Raspberry Pi
$ sudo reboot

Continue setting up Nocturne by following the steps outlined here. Then, select Login with Phone, scan the QR Code, and enter the Client ID and the Client Secret, and login to Spotify. After logging in, you are ready to use Nocturne!

Troubleshooting

superbird-tool: USBTimeoutError

If you are running into this error while flashing your Car Thing, try using the option --slow_burn or --slower_burn in the command used to flash.

This will look like the following:

$ python ./superbird_tool.py --dont_reset --slow_burn --restore_device /path/to/nocturne/image

If this still does not resolve the error, then you will have to edit line 164 (the one that says MULTIPLIER = 8) in superbird_device.py

If your flashing is failing at executing bulkcmd: "amlmmc part 1", then try running the following command manually. This may take a few tries to succeed:

$ python ./superbird_tool.py --bulkcmd "amlmmc part 1"

python in the above commands depends on what OS you are running:

  • For Windows, it will be python
  • For macOS, it will be /opt/homebrew/bin/python3
  • For Linux, it will be python3

superbird-tool: "bulkcmd timed out or failed!" after system_b

If you are running into this error while flashing your Car Thing, you must replace the superbird_partitions.py file in thesuperbird-tool folder with the one provided in this repo.

This error occurs since some devices have a smaller data partition, causing the error when attempting to flash the data partition.

superbird-tool: AssertionError

If you are running into this error while flashing your Car Thing, you must install the libusbk driver in Zadig. You can do this with the steps found here, and replacing libusb-win32 with libusbk instead.

If your issue is not listed here, or if you need help, join our Discord server for assistance.

Download

You can download the latest flashable version of Nocturne for Windows, macOS and Linux here.