Getting your Dream Recorder set up

Building the device

📄 Assembly Guide (PDF)

Installing & configuring the OS

💻️ On your computer

Download and install the Raspberry Pi imager software - https://www.raspberrypi.com/software/
Plug the micro SD card into your computer using an SD card reader
Open the Raspberry Pi imager software and install it using the following details:
- Raspberry Pi OS (64-bit)
- Choose to edit the customisation settings
  - General:
    - Hostname: dreamer
    - Username: dreamer
    - Password: (choose a simple password)
    - Type in your WiFi network's SSID & password carefully
  - Services: Enable SSH using password authentication
Once the installation has finished, safely eject and remove the microSD card

See step-by-step images 🖼️

🍓 On the Raspberry Pi

Insert the microSD card into the Raspberry Pi
Plug the Raspberry Pi in using the power supply and wait for it to boot up

Finding the Raspberry Pi's local IP address

You now need to find the IP address that your local network has assigned to the Raspberry Pi. You can do this in one of three ways:

EASY: On the device:
- Plug a USB mouse in to the Raspberry Pi
- Click on the Wifi icon on the top right of the screen
- Advanced Options -> Connection Information
- Note the IP address (e.g. 192.168.1.100)
- ...or...
MEDIUM: On your network router's admin software interface:
- This approach's exact steps will depend on what your home network's router and software is
- Essentially you will need to find all connected devices and find the Raspberry Pi
- ...or...
HARD: In a Terminal console on your computer:
- Open up a terminal window
- Check if you have nmap installed by running:
  - nmap
  - If it's not installed, do so now - Downloads & instructions
- Find your computer's IP by either:
  1. Running this command in the terminal:
    - ifconfig | grep "inet "
    - Make a note of your computer's IP address (which will most likely look something like 192.168.X.X)
    - ...or...
  2. Referring to your computer's Wifi / Ethernet connection details via settings
- Run this command in the terminal, keeping the first three numbers sets the same as your computer's IP and leaving the 0/24 at the end:
  - nmap -sn 192.168.1.0/24 | grep dreamer
  - So if your computer's IP address is 192.168.1.100 for example, you would run: nmap -sn 192.168.1.0/24 | grep dreamer

💻️ On your computer (in a Terminal window)

Open up a terminal / command line / bash window
SSH into the Dream Recorder with the following command, using the simple password you created in the Raspberry Pi imager:
- ssh dreamer@<DREAM_RECORDER_IP_ADDRESS>
Run the Raspberry Pi config tool by running this command:
- sudo raspi-config
- Interface Options -> VNC -> Yes -> OK
- Localisation Options -> Configure time zone -> Choose your country & city
- Select <Finish>
Keep this terminal window open for later

See step-by-step images 🖼️

Getting yourself connected to the Pi

💻️ On your computer

Download RealVNC, install and run it
- Connect to the Dream Recorder using the hostname (dreamer), the username (dreamer) and your simple password
- You now have remote desktop access to the Raspberry Pi
- Change the screen's orientation:
  - Click the Raspberry Pi icon (top left) -> Preferences -> Screen Configuration
  - Right click on the HDMI-A-1 screen -> Orientation -> "Right" -> OK
  - Drag the window to the left so you can click the "Apply" button
  - Navigating with the mouse might become tricky now, so you can use your keyboard as follows:
    - <tab> <tab> <spacebar>
- Close RealVNC

See step-by-step images 🖼️

💻️ On your computer (in a web browser)

Generate an API key for OpenAI:
- Login / sign up to OpenAI and create a secret / API key
- Copy the value and paste it to a text file temporarily as you will need it shortly
- Add a few dollars of credits to your account (~$5 suggested)
Generate an API key for LumaLabs:
- Login / sign up to LumaLabs and create a secret / API key
- Copy the value and paste it to a text file temporarily as you will need it shortly
- Add a few dollars of credits to your account (~$20 suggested)
Copy the URL of the Git repository at the top of this Github page by clicking on the Code button at the top right and copying the 'HTTP' url

💻️ On your computer (in the Terminal window)

Make sure you are still connected to the Dream Recorder
- If not, connect again:
  - ssh dreamer@<DREAM_RECORDER_IP_ADDRESS>
Clone the Dream Recorder from Github using the URL you just copied in the step above
- git clone <repo_ssh_url>
Once completed, navigate into the repo folder:
- cd dream-recorder
Run the installer:
- ./pi_installer.sh
- When prompted, paste in each of the API keys you generated above
Reboot the Raspberry Pi: sudo reboot
You are now up and running once the Pi has rebooted!

Using the Dream Recorder

Single tap: Play the latest dream
- Single tapping while a dream is playing will play the previous dream
- Double tapping while a dream is playing will go back to clock mode
Double tap: Record a dream
- Single tap once you are done talking for the dream to be generated

You should be good to go with your Dream Recorder now! Everything below is mostly for those that want to take things further to start tinkering and contributing

Configuring the Dream Recorder (optional)

To change the default settings for the Dream Recorder, you can use the command line configuration tool:

SSH into the Dream Recorder with the following command, using the simple password you created in the Raspberry Pi imager:
- ssh dreamer@<DREAM_RECORDER_IP_ADDRESS>
Navigate to the Dream Recorder's root folder:
- cd dream-recorder
Run this command: ./dreamctl config
After saving (s) and quitting (q), reload the application (if you've changed any core, non-superficial configurations) by running:
- docker compose restart

See step-by-step images 🖼️

Printing the enclosure

In the ./3DAssets folder you will find STL and G-code files for the translucent two-part 3D-printable enclosure. Designed with accessibility in mind, it should print reliably on most FDM printers using basic slicer settings.

Files included

FilenameDescriptiondream-recorder_front.stlFront half of the enclosuredream-recorder_back.stlBack half of the enclosuredream-recorder_front.gcodePre-sliced G-code for front shelldream-recorder_back.gcodePre-sliced G-code for back shell

G-code was sliced for a 0.4 mm nozzle with standard PLA settings at 0.2 mm layer height.

Recommended print settings

SettingValueLayer height0.2 mmNozzle diameter0.4 mmInfill15%, RectilinearWall loops2Top/Bottom Layers4 (Monotonic pattern)SupportsEnabled, Tree (Auto)Support angle45°Flush optionsFlush into support: ✔️MaterialTranslucent PLA recommended

Note: Prime tower is disabled to ensure simplicity and material efficiency.

Compatibility & customization

Optimized for standard 0.2 mm settings, but prints well across a range of layer heights
You can use your own slicer or directly print using the included .gcode files (assuming printer compatibility)

Orientation on the printer bed

Assembly Instructions

Print both front and back pieces
Remove supports carefully (tree structures minimize scarring)
Clean up seam edges with light sanding if needed
Press-fit the two parts together (t)he enclosure is designed for a friction fit, so no glue or fasteners required)

Taking things further

To get the Dream Recorder up and running on your local machine (for developers & contributors)

Note: You will need Docker (Compose) installed on your system - Docker documentation

git clone <repo_url>
cd dream-recorder
cp ./.env.example ./.env
cp ./config.example.json ./config.json
# Add your API keys using vim, nano or any text editor you're compfortable with
vim .env
docker compose -f docker-compose.dev.yml build
docker compose -f docker-compose.dev.yml up -d
# Edit the default config options (optional)
./dreamctl config

The app will be available at http://localhost:5000 (unless you choose to change the default port in the config)

To simulate sensor button presses, you can either use the on-screen developer console (available when running in dev mode), or:

Note: You will need Python 3.12 installed on your system - Python documentation

python gpio_service.py --test

See step-by-step images 🖼️

Running unit tests

Run this command to run the tests:

./dreamctl test Run this command to run the tests and see overall test coverage:
./dreamctl test-cov

See step-by-step images 🖼️

Visual diagrams

To see how the application's architecture and communication works visually, please refer to the Mermaid diagrams:

📈 Application Architecture
📈 Conversation flow

Managing your dreams

You can access the dream management page from your computer by going to http://dreamer:5000/dreams

See step-by-step images 🖼️

Troubleshooting

Logs:
- App logs: docker compose logs -f
- GPIO logs: ./dreamctl gpio-logs (for on the Dream Recorder)
- GPIO logs: tail -f logs/gpio_service.log (for during development on your local machine if using python gpio_service.py --test)

Check running services:

docker ps
ps aux | grep gpio_service.py
ps aux | grep chromium-browser

Stop the services:

docker compose down
systemctl --user stop dream_recorder_gpio.service

Restart the services:

docker compose up -d
systemctl --user start dream_recorder_gpio.service

dreamctl: Simple Command Runner

To make working with the Dream Recorder easier, you can use the dreamctl script in the project root. This script simplifies running common commands inside the Docker container.

Usage:

./dreamctl <command>

Available commands:

config Edit the Dream Recorder configuration
test Run unit tests
test-cov Run unit tests with coverage report
gpio-logs Tail the GPIO service log (logs/gpio_service.log)
help Show help message

For example:

./dreamctl config will open the configuration editor
./dreamctl test will run the test suite
./dreamctl test-cov will run the test suite with coverage reporting
./dreamctl gpio-logs will tail the GPIO service log (logs/gpio_service.log)

You can extend dreamctl to add more commands as needed.

Wishlist / Roadmap / Todos

If you would like to contribute to the project, here are some areas we would love help / contribution towards:

Improving on the shopping list:
- Including better, more local options (globally) that are not Amazon
- Finding more efficient purchases for larger packaged items, such as the Dupont cables, nylon screwsets, etc...
Building out support for multiple (by configuration) AI providers:
- Support for alternative STT and/or prompt generation providers (Claude, Gemini, etc...)
- Support for alternative video generation providers
Adding in support for config-based screen-blanking between configurable times

Dream Recorder

Discussion