recurBOY FAQ TROUBLESHOOTING guide

Welcome to the recurBOY FAQ / TROUBLESHOOTING guide

despite my best efforts, since the recurBOY is software running on a small computer disguised as hardware, there are still plenty of ways things can go wrong. this page should outline some of the common questions / issues and how to fix them. feel free to add to this page also if you can.

my recurBOY doesnt start / is stuck on color-gradient

this can happen if the operating system / file system gets corrupted - the easiest way to restore your recurBOY from this is to reflash the image to the sd-card - see next entry. one of the most common reasons this happens is if the rpi computer is unplugged while in the middle of a write operation. a good way to avoid this happening is by always safely shutting down the recurBOY before removing power by holding down the PLAY/PAUSE until the screen turns white.

i have had reports of corrupted file systems despite safe power downs - possibly related to long use of usb-camera inputs - if you think you can reproduce this happening reliability please open an issue here and i will try to fix it

how to reflash the recurBOY image

download the lastest image - link can be found on the releases page - be aware that it is a 1.8gb file and may take some time.
download a program to burn the image to the sd card - i use etcher (but there are others including the official raspberry pi imager )
remove the micro-sd card from recurBOY and put into your computer
using etcher select the image file ( eg recurboy_v2_1_1.iso.gz ) and the sd-card location and let it burn.
when this is finished put card back into (unpowered) recurBOY and then reconnect the power

NOTE: when recurBOY is booted for the first time from a new flash it will automatically reset itself shortly after loading - this is normal to expand the file-system - just wait for it to load up for the second time and your recurBOY will be ready to use

NOTE: the default image outputs NTSC video - if you are in a PAL region you will also need to change this - see below

how to change the composite video output format

by default the recurBOY image outputs composite video in NTSC format. if you require PAL video you can change it by following these steps:

power down recurBOY and remove the sd-card.
put the sd card into a computer
open up the boot partition that should mount when the card is inserted
on the top level of this partition open with a text-editor the file config.txt
locate in this file the line that says: sdtv_mode -> set this to sdtv_mode=2 for PAL or sdtv_mode=0 for NTSC

Composite video mode options

sdtv_mode

The sdtv_mode command defines the TV standard used for composite video output. On the original Raspberry Pi, composite video is output on the RCA socket. On other Raspberry Pi's, except for Pi Zero and Compute Module, composite video is output along with sound on the 4 pole TRRS ("headphone") socket. On the Pi Zero, there is an unpopulated header labelled "TV" which outputs composite video. On the Compute Module, composite video is available via the TVDAC pin. The default value of sdtv_mode is 0.

sdtv_mode	result
0	Normal NTSC
1	Japanese version of NTSC – no pedestal
2	Normal PAL
3	Brazilian version of PAL – 525/60 rather than 625/50, different subcarrier
16	Progressive scan NTSC
18	Progressive scan PAL

sdtv_disable_colourburst

Setting sdtv_disable_colourburst to 1 disables colourburst on composite video output. The picture will be displayed in monochrome, but it may appear sharper.

NOTE: in the next software update i plan to make this switchable within the recurBOY app - see this issue

how do i load my own videos / shaders onto the recurBOY ?

via a usb-drive

the easiest way to access custom content on the recurBOY is to put it onto a usb-stick and then attach the usb-stick to the recurBOY DATA-MICRO-USB port via the OTG usb cable.

create folders in the top level of your removable drive storage called: Videos , Shaders, Fx
put your videos/shaders file into these folders
while recurBOY is powered down plug the usb-stick into the OTG-USB-CABLE and the other end of cable into the inner micro-usb port on recurBOY (outer one is power only)
boot up recurBOY and you should see your custom content in the list

via mounting the sd-card onto a linux computer

if you do not have a linux computer you can still use this method by live-booting into a linux os using a usb-stick and then from here access the file system on the sd

when you mount the sd-card on a linux system you should see two partitions: boot and rootfs - by opening the rootfs one you should find the folders where content is loaded from at /home/pi/Videos, /home/pi/Shaders, /home/pi/Fx - put your files in here (also you can remove the default ones that you do not want)

via SSH

while the recurBOY is running you can also access files on the recurBOY from your computer using SSH if they are both on the same network.

if your rpi_zero has wifi you can connect it to your home wifi and use this network to ssh from your computer.

how to connect your rpi to wifi

power down recurBOY, remove the sd-card and put it into a computer
open the boot partition and create a new file called: wpa_supplicant.conf with content:

country=YOUR_COUNTRY_CODE
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="YOUR_SSID"
    psk="YOUR_PASSWORD"
    key_mgmt=WPA-PSK
}

NOTE: for security reasons you should change the default password into your pi if you are connecting it to a wireless network

if you are not on a wifi network or your pi_zero does not have wifi you can still create a wired network connection:

with the sd-card in the recurBOY connect the DATA-MICRO-USB (middle one) to your computer using a micro-usb cable
after the recurBOY powers on it should establish a network connection with the computer - you can test this by entering ping raspberrypi.local into your computers terminal (if this does not work you may need to disable firewall)
now you can ssh into the recurBOY by running ssh [email protected] and entering raspberry as the password
to copy files across a network you can use scp for example:

scp ~/Videos/a_video.mkv [email protected]:/home/pi/Videos/

NOTE: if you are running windows you may need to install putty first

my recurBOY has a few lines of random pixels on side/top of the display - how do i fix this?

this is due to some batches of displays being slightly different from others. it can be fixed by modifying a few lines in the display.py code - you can get here by following the ssh / mounting sd-card on linux guides above :

you need to edit these lines in the file /home/pi/recurBoy/software/display.py :

WIDTH = 130 #128
HEIGHT = 161 #160

NOTE: in the next software update i plan to make this switchable within the recurBOY app - see this issue

how do i use the 16pin eurorack footprint on the pcb to power recurBOY ?

this was added as an optional extra / after-thought and is not very well documented. but you can power recurBOY through a 16pin eurorack header IF your eurorack power supply already sends +5v - attach the header like this:

_NOTE: there is a good suggestion here to update this to be in line with other modules / be clearer what the orientation should be - i will try implement this in a future revision _

i have added a lot of custom videos / shaders to recurBOY but they are not all showing up ?

there is currently a bug preventing long lists of file names being displayed correctly - i will have this issue fixed in the next software update

what usb-cameras are supported by the recurBOY ?

recurBOY can process external video by attaching a usb camera / capture card to the OTG cable before powering it up. this was originally a 'hidden' feature as i did not expect the pi_zero to be able to process video input over usb - i was pleasantly surprised with the inputs i tested however i can not test everything.

the two types of inputs that i have seen working with recurBOY are:

EASYCAP USB 2.0 Capture Digital Video Converter
an old logitech webcam i found at the tip

feel free to update this list if you have tested more.

if you are using a lot of external video input consider upgrading your pi_zero to a pi_zero2 which should have more resources for usb-capture

what is this extra smd ic / unlabeled footprint on the pcb?

this is a dual footprint for the MCP3008 analog-to-digital ic -> its meant to give you the option to source this ic in either smd or dip (not both)

this is because in some cases it is easier / cheaper to source the smd version, but also some people who are getting into diy may still prefer to source the tht version

take note of the direction of the ic indicated by the arrows on the silkscreen -> direction is reversed depending on the selection

Provide feedback

Saved searches

Use saved searches to filter your results more quickly