Troubleshoot TJBot

Having trouble getting your TJBot working? You've come to the right place. This section provides general tips for troubleshooting your TJBot followed by an FAQ-style guide for common hardware issues. Don't see what you're looking for? Open an issue and we'll try to help!

General troubleshooting tips

Software debugging

TJBot's library is configured to emit various levels of information that may be a useful debugging aid. You can configure its logging level by adjusting the log.level setting in your tjbot.toml file:

[log]
# Valid logging levels are 'error', 'warning', 'info', 'verbose', 'debug'
# Set this to 'error' or 'warning' to reduce log verbosity
# Set this to 'verbose' or 'debug' to see detailed logs for troubleshooting
level = 'info'

Low-level hardware tests

TJBot includes a nubmer of low-level hardware tests that bypass its software library and speak straight to the underlying hardware. These tests can help you understand whether your issues are due to actual hardware problems or simply a misconfiguration in your tjbot.toml file.

These tests are bundled as part of the node-tjbotlib repository, not, the tjbot repository. You can access them here:

cd ~/.tjbot/node_modules/node-tjbotlib/scripts

The test scripts are as follows:

• test-commonanode.js: Tests a Common Anode LED. The test has interactive prompts for you to specify the pins to which the LED is connected.
• test-neopixel-direct.js: Tests a NeoPixel LED via the direct ws281x interface, which requires root priveleges
• test-neopixel-ipc.js: Tests a NeoPixel LED via the IPC interface, which launches a privileged helper process to drive the LED
• test-neopixel-spi.js: Tests a NeoPixel LED via the SPI interface, used on Raspberry Pi 5
• test-servo.js: Tests the servo hardware

The tests are written in JavaScript and can be run directly with node. For example:

node test-commonanode.js

Note

The test-neopixel-direct.js test must be run with sudo as addressing the LED using the ws281x library requires root access.

LED issues

My LED doesn't light up

If the LED does not light up, you can try moving the power from 3.3 to 5 volts. If neither the +3.3v or +5v pins work, you will need a 1N4001 diode. Insert the diode between the power pin of the LED and the +5v pin on the Raspberry Pi.

My NeoPixel LED inverts red and green

By default, TJBot sends colors to NeoPixel LEDs in the "GRB" format. If your LED is shining green when it should shine red, and red when it should shine green, then you should set shine.useGRBFormat to false in your tjbot.toml file.

Tip

If you are using a Raspberry Pi 5, you will likely need to set shine.useGRBFormat to false.

[RPi 3] My LED shows the wrong color, rapidly flashes different colors, or flashes when audio is playing

On Raspberry Pi 3, if the LED shows the wrong color, rapidly flashes different colors, or flashes when audio is playing, it may be due to interference with the built-in audio hardware. On this hardware, TJBot's bootstrap script will ask if you wish to disable the sound kernel modules. It is safe to re-run TJBot's bootstrap script to do this:

sudo --preserve-env=PATH bash bootstrap

Note

The bootstrap script requires root privileges, but by default, sudo does not inherit the user's $PATH. Therefore, running sudo bootstrap will not succeed because the shell won't be able to find the bootstrap script.

When TJBot prompts you to disable the sound kernel modules, say "DISABLE".

On Raspberry Pi 3 models, there is a known conflict between the LED
and the built-in audio jack. In order for the LED to work, we need to
disable certain kernel modules to avoid this conflict. If you have
plugged in a speaker via HDMI, USB, or Bluetooth, this is a safe
operation and you will be able to play sound and use the LED at the
same time. If you plan to use the built-in audio jack, we recommend
NOT disabling the sound kernel modules.
Enable or disable sound kernel modules? [DISABLE/enable]

Reboot, then use lsmod to confirm the "snd_bcm2835" module is not loaded.

sudo reboot
... wait for TJBot to reboot ...
lsmod | grep snd_bcm2835

I'm still having trouble with my NeoPixel LED

If you have additional NeoPixel LED difficulties not covered in this guide, please refer to Adafruit's NeoPixel on Raspbeery Pi guide to troubleshoot.

Speaker issues

My Bluetooth speaker doesn't play audio

Many people have reported numerous issues regarding Bluetooth speakers and TJBot. We do not recommend using a Bluetooth speaker with TJBot, as we have never reliably been able to make it work. In some instances, audio works over Bluetooth but when TJBot speaks, the speech is clipped (e.g. the first word is dropped) or garbled. In other instances, audio fails to work at all over Bluetooth, even when it works outside of TJBot (e.g. with ALSA's aplay command). Therefore, we recommend using a USB audio adapter and connecting a speaker to its 3.5mm audio jack.

Servo issues

TJBot's arm is waving backwards or upside-down

Different servo models may use different "stop points" to set the position of the servo. TJBot's software library uses a set of stop points that work with SG90 servos. If these stop points don't work for your servo, try experimentally redefining the stop points defined in node-tjbotlib/scripts/test-servo.js:

const positions = [
    ['back', 700],
    ['up', 1400],
    ['down', 2300],
    ['up', 1400],
];

Once you find a set of stop points that work for you, you can update them in node-tjbotlib/src/servo/servo-constants.ts:

export enum ServoPosition {
    ARM_BACK = 700,
    ARM_UP = 1400,
    ARM_DOWN = 2300,
}

Please refer to the contributor's guide for instructions on how to set up a local development environment, build TJBot's library locally, and link your recipes to it.

Can I forcibly twist the servo motor to fix its alignment?

No, please don't do this. Servo motors are somewhat sensitive to manual interference. If you forcably twist the servo motor, you may end up breaking it. If there is an alignment issue with the servo motor's arm, we recommend unscrewing and reattaching it.