Billy Bass
Operating and repair manual

Meet Billy

Billy is a custom talking fish built around a small Raspberry Pi computer. A microphone hears questions, local software chooses or writes a reply, speakers play it, and motors move the mouth and body. A camera can notice someone facing Billy. The small e-paper screen displays a name tag, words, or sleep status.

You do not need to program Billy to use him. Begin with sections 1 and 2. Sections 4 through 8 explain the browser controls. Wiring, internal repair, and software updates are for the person maintaining the unit.

What comes from where

Offline conversation and local networking

Installed speech and answer models run on the Pi, without Internet access for ordinary conversation. For the controls, a phone or computer connects directly to Billy’s private service Wi-Fi. No venue router, Wi-Fi password or Internet connection is needed. [R1, P1]

Prepared responses can begin much sooner than newly generated answers. Give Billy time to finish rather than repeating the question immediately. Generated answers can be wrong, even about Billy himself; this is a novelty project, not an authoritative adviser.

Support

Thomas Acampora
acamporat@pm.me
(858) 774-4457

For help, send the symptom, what happened just before it, and a photo of the status/error message. Do not send passwords, secret files, or recordings of other people without permission.

1 Start here

This manual is for the operator and maintainer of the Raspberry Pi Billy Bass: local conversation, moving mouth and body, camera engagement, microphone, speakers, e-paper name tag, and the browser developer console. Start with the daily checklist. Use the diagnostic sections to isolate one fault at a time.

Edition 24 September 2026. Instructions combine the installed Pi configuration checked on 24 September 2026 with the project source. Future releases can differ. Before changing hardware or software, identify the running release in Section 3 and compare its configuration. Wiring diagrams describe electrical connections, not a photograph or proof of the assembled harness.

2 Daily operation

Unpacking and first placement

1. Lift Billy by the plaque or enclosure, not the head, tail, wires, camera or display. Remove all loose packing from the movement area.
2. Set the unit on a stable indoor surface or use its intended secure mounting. Keep it dry, ventilated, and away from a table edge. Do not restrain the moving head or tail.
3. Find the supplied, labeled Pi power connection and motor-power control. If either is unlabeled, loose, or damaged, contact Thomas before connecting it.
4. Keep the preinstalled microSD card in place. Do not follow a generic Raspberry Pi imaging tutorial to set up this assembled unit.

Optional service Wi-Fi from your phone

No venue network is needed. Billy runs offline. Use the service hotspot only when you want the controls.

1. With Billy powered on, open your phone’s Wi-Fi settings and join BillyBass-Service using the password on the private shipping label.
2. If your phone says “No Internet,” choose Stay connected or Use without Internet. This is expected.
3. Open a normal browser and enter http://10.42.0.1:8080. Include http and port 8080; no app installation or Internet login is needed.
4. If the page will not open, check that Wi-Fi stayed on BillyBass-Service. Temporarily turn off a VPN or automatic cellular switching if needed. Restore your phone settings afterward.
5. If Billy is sleeping, say Hey wake up before running tests. The console can remain reachable during sleep while most actions are blocked.
6. When finished, return your phone to its normal Wi-Fi. Billy continues working offline.

The hotspot is a normal Wi-Fi access point that phones can join directly. It does not route users to the Internet or to another connected network. Share its password only with trusted operators. [P6]

Before visitors arrive

1. Check that the case is secure, the mouth/body can move freely, the speaker leads are insulated, and no connector is loose. Keep the motor-power switch accessible.
2. For an already accepted assembly, connect the Pi’s proper USB-C supply. Leave motor power off while checking readiness. After a repair, use the staged procedure in Section 11 instead.
3. For optional status checks, join BillyBass-Service and open http://10.42.0.1:8080. Normal use does not require opening the console.
4. If the screen says SLEEPING, say “Hey wake up.” Check listener readiness and Brain Status. Allow models to load; do not run several heavy tests during startup.
5. Run a brief microphone check, stop it, and play one short audio-only line at a conservative volume. Check the e-paper message and camera framing.
6. With the mechanism clear, enable the accepted motor supply and run one supervised short motion check. Then test a real spoken question and watch mouth movement.
7. Enable Hey Billy listener and Face engagement as desired. Close the live preview when finished; background face watching can remain active.

Talking to Billy

1. Face the camera for about 1.2 seconds, or say Hey Billy.
2. Watch for the listening state and ask a question naturally. Older runtime versions say “Go ahead”; the realtime profile disables that preliminary cue.
3. Wait for the reply. Ask a follow-up while the session remains open. About ten seconds without speech returns Billy to standby.
4. On the realtime runtime, speak during an answer to interrupt it. Say stop listening or goodbye Billy to end the session. Use Software Stop if necessary.

Face activation uses position, angle, confidence, and dwell time. It does not identify people. A continuously visible face does not repeatedly open sessions; look away or leave the view before trying again. Billy answers locally and cannot check live weather or current news. Check consequential answers independently.

Sleep without shutting down

Say “Hey Billy, take a nap.” Billy stops speech and movement, pauses face engagement and idle invitations, and listens for “Hey wake up.” The screen shows SLEEPING. After waking, ask your question; you do not need another “Hey Billy” first. Sleep is quiet standby: the Pi and microphone remain powered. It can survive a restart. [P3]

Optional songs

On a release with the prepared song library, ask “Hey Billy, sing me a song.” Billy selects a song and can coordinate motion and screen content. For reliable cancellation use the front button or Software Stop. Do not rely on spoken interruption during songs: some playback paths release the listening device. If the song files are absent or there is an audio error, stop and contact Thomas rather than repeatedly retrying.

End of day

1. Use Software Stop. Disable face engagement and the listener, and switch off motor power.
2. Hold the front button for three continuous seconds (or press it three times quickly), or run sudo shutdown -h now on the Pi.
3. Wait for the Pi to halt before removing its power. Restart using the startup method marked for this unit. Voice wake works only in sleep mode; wake from a full shutdown depends on Pi firmware and the installed power arrangement. Do not assume the front button can restart a halted Pi.

The front button is a stop and shutdown control, not a conversation trigger. One click requests Software Stop after the click-detection window (about 0.75 seconds). Three quick clicks request shutdown; holding for three seconds also requests shutdown. Its wiring occupies GPIO3; do not enable I2C1 on that pin. [P2]

3 Identify the installed system

The web service owns the current realtime conversation loop. Do not also start the older booth loop or a second web process: they can compete for audio, camera, port 8080, or the motion lock. The example project path below is the documented Pi path; confirm it from the service before relying on it.

ssh swa@raspberrypi.local
systemctl cat billybass-web.service
systemctl status billybass-web.service billybass-llm.service --no-pager
curl -s http://127.0.0.1:8080/api/hotword/state
readlink -f ~/CybersecurityMonthAIBass/current
vcgencmd get_throttled

Read WorkingDirectory and ExecStart in the service definition. Work from that directory and use its virtual environment. On a staged deployment, the current link identifies the selected release; the API’s realtime.release and realtime.ready identify the resident runtime and readiness. A selected symlink alone does not prove healthy activation.

4 Developer UI and function tests

Use this order when diagnosing a full conversation: silent answer → audio-only line → live mic recording → spoken answer → motion. This keeps a faulty microphone from being confused with a model or speaker problem.

The console can actuate hardware and edit content. Keep it on a trusted LAN; do not forward port 8080 to the Internet. This manual’s screenshots show actual HTML/CSS copied from the installed release on 24 September 2026, with application scripts disabled so no test command was sent.

5 Microphone listening and volume

Check the microphone

1. Pause automatic conversation if it interferes with testing. Choose a short Auto-stop interval and start at Recording gain +0 dB.
2. Select Start Mic Test. Speak from the intended visitor position. Watch the level meter; it should rise with speech and fall in quiet.
3. Stop the test and play the recording in the browser. Browser playback comes from the computer’s output, not necessarily Billy’s speaker.
4. If the recording is quiet, raise recording gain in small steps. If it sounds harsh or stays near 0 dBFS, reduce gain or move back.
5. Stop the test before returning to conversation. Confirm listener readiness returns.

The meter’s recording gain is a diagnostic setting, separate from playback volume and the runtime’s speech-recognition gain. The temporary recording is overwritten by the next test. Do not use a mic test as a reason to leave visitor recordings around.

Set speaker level

Playback volume is digital attenuation from 0 to 100%; it does not change microphone sensitivity. The value persists in run/playback-volume.json. At 100% it supplies unity gain, not a measured safe acoustic level.

1. Start with a short audio-only phrase at a low slider setting.
2. For the dedicated Live Speaker Level Test, remain beside the speakers and check its acknowledgement. It repeats for at most 20 seconds.
3. Raise the slider only as needed. Use Stop Speaker Test promptly for distortion, heat, odor, clicking, or excessive cone movement.

6 Motion and Voice Lab

1. Keep the mechanism clear and the physical motor-power switch within reach. Stop any separate legacy booth process. A GPIO ownership error is a reason to find the owner, not delete a live lock.
2. Check the displayed backend. A virtual fish moving under mock does not mean a motor moved.
3. Check the supervision box and select Enable test controls. This permits multiple bounded commands for up to one hour.
4. Choose a short duration and test Pulse mouth once. Observe the mouth; then test Pulse body once. Stop if the wrong mechanism moves.
5. Use Scripted mouth pattern (no audio) to separate mechanics from speech. It is real movement on a GPIO backend.
6. Enter a short line under Type & perform and use Speak + sync mouth. This path accepts up to 500 characters.
7. Select Software Stop or Disable test controls when finished. Software Stop cancels current work and ends the supervised session.

These values describe the read-only installed configuration snapshot. Confirm the active release’s values before diagnosing a changed assembly. Do not increase strength or duration to overcome a stalled linkage.

7 Camera and e paper

Camera

1. Select Start Live Overlay in Camera And Media. Choose Smooth for 640×480 or Detailed for 1280×720.
2. Frame a full face near the center at visitor height. Observe whether the overlay tracks the face and its angle.
3. Use Stop Live before changing cables or trying independent capture tools. Closing preview does not disable background face watching; use the Face engagement switch for that.
4. Test actual face-start listening after preview checks. A detection rectangle alone does not prove the stricter background activation gate passed.

The configured Camera Module 3 NoIR uses the imx708 sensor and a Pi 5 22-pin-to-15-pin Standard-Mini cable. Current configuration rotates the image 180 degrees. Inspect cable seating with all power removed. Do not repeatedly launch competing camera tools to solve a busy-camera error.

E paper

1. Enter up to 250 characters and select Show message. This does not speak or move the fish.
2. Wait through queued work and refresh. The preview represents the last image sent by the driver; inspect the physical screen.
3. Select Restore name tag to restore “Hello, my name is Billy”. A manual message remains until another spoken response or restore request.

Speech normally mirrors text and returns to the name tag about ten seconds after playback ends. Realtime longer answers can page text. E-paper refreshes are slow and coalesced; repeated clicks do not make them faster. A retained image after power-off is normal and is not proof that the Pi is still running.

8 Edit questions and answers

1. Back up the knowledge file before editing: content/camping_2026/knowledge.yaml.
2. Open Q&A Management. Select or add a Source; give it a stable Source ID, title, reference, and notes.
3. Select or add a Topic. Fill in its stable Topic ID, title, keywords, likely questions, and matching Source IDs.
4. Write the Approved Answer as the factual reference and the Billy Voice Line as the spoken version. Check both for accuracy and pronunciation.
5. Select Save Knowledge File. Check the result in Activity Log before leaving the page.
6. After changing spoken text, use Generate Selected WAV, then Play Selected WAV and listen. Generate Missing WAVs fills missing cache entries; do not assume it refreshes every edited existing recording.
7. Return to Function Tests. Try the exact question and several natural paraphrases, first silently, then aloud.

Conversation mode can generate a response using reviewed guidance. Editing a topic does not force every answer to be a verbatim voice line. Prepared caches and the resident conversation voice can differ. Deleting topics or sources changes the saved content; retain a recoverable copy.

Older documentation describes QR cards and station completion. The current UI and source have removed that workflow; this manual does not present it as an available operator function.

9 Wiring overview

With all power disconnected, identify pin 1 using the Pi’s board marking or verified board pinout. Odd pins run 1, 3, …, 39 along one row and even pins 2, 4, …, 40 alongside them. The diagram below is a numbering aid, not an orientation view relative to the USB sockets.

Use terminal labels and continuity, not wire color alone. Photograph and label every connector before removal. Switch off both Pi and motor supplies before resistance measurements. Never connect an amplifier speaker output to ground: SPK+ and SPK− are both driven.

10 Connection tables

Custom harness reference [P5]; component principles [R2–R5]. Disconnect both power sources before wiring.

Audio

Speaker series circuit: SPK+ → driver 1 +; driver 1 − → driver 2 +; driver 2 − → SPK−. Verify the disconnected pair at its final two leads. Do not substitute parallel wiring or join either lead to Pi ground. Share the I2S clocks using secure junctions; mic DOUT and amp DIN must stay separate.

Motor driver and relay

NPN terminal names are electrical functions, not left-to-right leg order. Identify the installed transistor and its pinout. Relay COM/NO/NC contact placement, fuse/current-limit values, and exact motor supply hardware must be verified on the assembly; the repository does not provide a complete construction drawing for that power path. The Pi relay supply must never become the motor supply.

Display and shutdown button

Use individual wires for the Waveshare V4; do not seat the stock HAT pin arrangement over the Pi. BCM17 and BCM24 are motor pins. Leave the unidentified stock sensor, small piezo, and unused second driver disconnected. The conversation arcade button is unassigned in current configuration.

11 Safe repair and component replacement

Tools and preparation

Use a suitable screwdriver, insulated labels, camera, multimeter, and correctly rated replacement connectors. Electrical motor diagnosis also needs a known protected supply and a way to measure voltage under load. Do not probe a crowded powered header with loose meter tips.

1. Record the symptom, current release, last change, and any error. Save configuration and take close-up photographs.
2. Use Software Stop, switch off motor power, shut down the Pi, and disconnect every supply. Verify power is absent before continuity tests.
3. Open the case without pulling the harness. Label both ends of each lead. Replace one component or connection at a time.
4. Check for bent pins, damaged insulation, loose solder joints, pinched wires, jammed linkage, and incorrect terminal labels. Do not force the jaw or body against a hard stop.
5. Compare the traced wiring with Section 10 and the active configuration. Correct the cause before fitting a new board.

Replacing parts

Return to service in stages

1. Unpowered: check polarity, intended continuity, and absence of a hard short. Do not infer a fault from one capacitor-charging resistance reading.
2. Pi only: keep motor VM off and STBY disconnected. Confirm stable boot and no current undervoltage indication.
3. Audio and display: test microphone, a short quiet spoken phrase, one camera capture, and one e-paper refresh separately.
4. Motor logic: with motor supply still off, confirm the configured GPIO mapping and default-off relay behavior.
5. Motor power: use the verified protected supply, clear the linkage, then test one bounded channel at a time with its physical disconnect ready. A stall, hum, heat, or collapsing rail means stop and investigate.
6. Full interaction: hear a spoken answer, observe synchronized mouth and body return, interrupt speech, test Software Stop, and verify idle return. Record observations before allowing unattended operation.

12 Troubleshooting

Useful read only checks on the Pi

journalctl -u billybass-web.service -n 100 --no-pager
journalctl -u billybass-llm.service -n 80 --no-pager
systemctl status billybass-shutdown-button.service --no-pager
vcgencmd get_throttled
aplay -l
arecord -l
ls /dev/spidev0.0
curl -s http://127.0.0.1:8080/api/motion/state
curl -s http://127.0.0.1:8080/api/display/state

Both ALSA lists should expose the shared Google Voice HAT-compatible card. The legacy ALSA name is sndrpigooglevoi; the realtime device match is snd_rpi_googlevoicehat. One googlevoicehat-soundcard overlay owns the shared I2S controller. Do not add competing amp-only or microphone-only overlays.

If status says asleep, wake Billy before diagnosing blocked test controls. Sleep is intentional and can survive service restart. Capture logs before restarting. Once the mechanism is safe, an ordinary service restart is sudo systemctl restart billybass-web.service. Confirm Ready afterward and repeat a short physical interaction test.

13 Backup and recovery

Make a private backup before changing content, software, or hardware configuration. Run from the deployed project with its Python environment, and keep the resulting archive and checksum off the Pi as well as locally.

python3 scripts/backup_project.py create
python3 scripts/backup_project.py verify /private/path/backup.tar.gz

Creation defaults to ~/billybass-backups. A custom destination must be outside the source project and not an ancestor of it. Existing destinations must belong to the operator with mode 0700. Archives can contain .env credentials; keep them private.

The helper selects source, configuration, models, content, persistent audio, selected runtime data, and SQLite snapshots. It verifies sizes and hashes. It excludes virtual environments, logs, transient recordings, and Git. It is not a complete SD-card image or full realtime deployment backup: selected paths do not automatically capture service unit definitions, all release recovery records, or the native build directory. Release symlinks to shared files outside a selected root may be rejected.

1. Record the running release ID, resolved current path, model/voice identity, and systemctl cat output for the web, LLM, and shutdown services.
2. Verify the helper archive and compare its reported SHA-256 with the original sidecar after copying.
3. Keep a separate verified SD image or complete offline runtime recovery copy including native audio dependencies, release records, and OS configuration. Do not call recovery complete until a spare target boots and works.
4. Restore into a new empty private directory with restrictive permissions. Inspect the verified archive before extraction; preserve the existing installation.
5. Recreate dependencies for the Pi architecture. Check device configuration with motor backend set to mock and body disabled in the recovery copy. Run local checks there.
6. Install or select the recovered runtime deliberately; confirm readiness and repeat the staged hardware tests before putting it back into service.

14 Software maintenance

Do routine development on a separate checkout or staged release. Do not edit the active runtime while it serves visitors. Use the deployed base as the source of device settings; the Mac checkout alone does not establish the installed wiring or voice.

Local verification

uv run --with-requirements requirements-dev.txt ./scripts/check_local.sh

This hardware-free gate exercises software with mock motion. It cannot prove speaker sound, wiring, or mechanical behavior. scripts/preflight.py is also read only, but its older readiness policy may conflict with the accepted real-motion configuration; inspect a reported failure rather than resetting working hardware just to obtain a green report.

Subsequent realtime updates

1. Follow REALTIME_CONVERSATION.md to stage from the installed current release. Preserve the actual device settings and approved voice hashes.
2. Prepare the locked environment/native library, run the staged tests, verify model startup, and seal the release. Audition any changed voice before marking it approved.
3. From the verified staged release directory, use the subsequent-upgrade command below. It checks the installed base and readiness and restores the old target if activation fails.

sudo .venv/bin/python scripts/upgrade_realtime.py "$PWD"
# To undo this subsequent upgrade, run from that same release directory:
sudo .venv/bin/python scripts/upgrade_realtime.py "$PWD" --rollback

After activation, check the expected API release ID and realtime.ready: true, service restarts, journal errors, and power health. Then test a spoken question, follow-up, interruption, mouth synchronization, e-paper, and return to idle. A sealed release is not necessarily active.

activate_realtime.sh and rollback_realtime.sh are the initial migration path. They are different from subsequent upgrades; the initial activation script deliberately refuses existing managed-service recovery state. Do not choose a rollback script merely because its filename contains “rollback”. Match it to the operation that created the failed release.

15 Maintenance record and source map

Keep one entry per change. This turns future repair into comparison against an observed working state.

Where to find the implementation

Evidence priority for a repair: actual traced assembly and measurements → active release configuration and code → current checkout → historical notes. This manual resolves the old reversed motor-channel prose using the current configuration’s explicitly recorded physical mapping. It does not certify a rewired assembly.

16 Understand the behavior

Why some answers take longer

A prepared answer can reuse an existing recording. An unfamiliar question may need speech recognition, answer generation, and new speech synthesis. That extra work can create a noticeable pause. A changing status message is more useful than an assumed fixed response time. No latency benchmark or new listening test was performed for this edition.

Three different kinds of quiet

17 Plain language glossary

Care between uses

Shut down and remove all power before cleaning. Use a soft dry cloth. Keep liquids, spray cleaners and lubricant away from the camera, microphone, screen, speaker and mechanism. Inspect exposed cables and mounting before use. Store dry, with no load on the moving parts. For shipping, protect the plaque and electronics and prevent the unit moving inside the box; do not wedge packing into the motor linkage.

18 References and support

The project sources define this custom wiring and behavior. Manufacturer references explain component principles; their stock wiring examples do not override Billy’s remapped harness.

Project evidence

[P1] Installed Pi snapshot, 24 September 2026. Read-only API state, resolved current release, active configuration and service status. Release: hearing-model-20260924-01. Configuration and software readiness were checked; wiring, audible playback and motion were not retested.

[P2] Front button implementation. src/billybass/shutdown_button.py and installed /usr/local/libexec/billybass-shutdown-button.py. One click: stop; triple-click or three-second hold: shutdown. The installed service was active.

[P3] Sleep behavior. docs/SLEEP_MODE.md from the installed release and src/billybass/web.py. Sleep keeps the wake listener running and persists in run/asleep.

[P4] Volume calculation. src/billybass/playback.py, playback_volume. Digital gain is percentage divided by 100. Figure 9 is calculated, not measured.

[P5] Wiring and service history. docs/PI5_TONIGHT_BRINGUP.md, installed config/billybass.yaml, and docs/REALTIME_CONVERSATION.md. Older prose contains superseded channel, voice and button settings; use the dated installed snapshot and verify the actual harness.

[P6] Offline service Wi-Fi. docs/SERVICE_HOTSPOT.md and scripts/install_service_hotspot.sh. Installed 24 September: AP active at 10.42.0.1, boot service enabled, forwarding blocked, local console HTTP 200. A real phone connection and offline cold boot remain shipping checks.

Manufacturer documentation

[R1] Raspberry Pi Getting started. Power and headless network basics. raspberrypi.com/documentation/computers/getting-started.html. Consulted 24 September 2026. Use a supply suitable for the Pi model; do not re-image the supplied Billy card as routine setup.

[R2] Adafruit MAX98357 amplifier pinouts. learn.adafruit.com/adafruit-max98357-i2s-class-d-mono-amp/pinouts. Consulted 24 September 2026. Both speaker terminals are driven; neither is ground. The documented minimum nominal speaker impedance is 4 ohms. Billy’s historical DC resistance measurement does not establish nominal impedance.

[R3] Adafruit I2S MEMS microphone pinouts. learn.adafruit.com/adafruit-i2s-mems-microphone-breakout/pinouts. Consulted 24 September 2026. Check the exact installed microphone model and terminal markings; Billy’s harness uses 3.3 V and a dedicated data-input line.

[R4] Waveshare 2.13-inch e-Paper HAT manual. waveshare.com/wiki/2.13inch_e-Paper_HAT_Manual. Manufacturer reference for the V4 panel; web page could not be fully retrieved during preparation. Match the exact monochrome V4 hardware and retain Billy’s remapped pins.

[R5] SparkFun TB6612FNG hookup guide. learn.sparkfun.com/tutorials/tb6612fng-hookup-guide/all. Manufacturer learning reference for driver terminals and standby; full page access was restricted during preparation. It does not specify the assembled Billy motor rail or protection.

[R6] NetworkManager connection settings. networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/nm-settings-nmcli.html. AP mode and shared IPv4 settings; Billy’s separate firewall blocks forwarding. See P6 for installation and validation limits.

Get help

Thomas Acampora
acamporat@pm.me
(858) 774-4457

Include the edition date, release name if visible, symptom, last change, and a clear photo of the problem. Stop using the unit if a connector is damaged, movement binds, or anything overheats.