Troubleshooting and Diagnostics

Enable debug logging

To increase TinyPilot debug logging, run the following command to perform an upgrade that enables debug logging:

export TINYPILOT_INSTALL_VARS="tinypilot_enable_debug_logging=yes"
curl \
  --silent \
  --show-error \
  https://raw.githubusercontent.com/mtlynch/tinypilot/master/quick-install | \
    bash - && \
  sudo reboot

To disable debug logging, run the same command with tinypilot_enable_debug_logging=no.

Logs

You can find logs for TinyPilot through the following commands:

Log dump

TinyPilot comes with a log dumper script that pulls logs from relevant services on the device and allows you to upload them to a shareable URL:

/opt/tinypilot/dev-scripts/dump-logs

Browser console logs

If the TinyPilot web app is misbehaving, the first place to check is the JavaScript console. You can find this in most browsers by hitting F12 and selecting the "Console" tab.

TinyPilot server

TinyPilot runs on the device as a Python server. This app usually has the most instructive logs:

sudo journalctl -u tinypilot

uStreamer

TinyPilot uses uStreamer for video streaming. Check logs here if you're having issues seeing the remote screen.

sudo journalctl -u ustreamer

nginx

TinyPilot uses nginx as a web frontend to manage incoming connections. Problems usually aren't in nginx, but it's worth checking if none of the previous logs reveal anything useful.

sudo journalctl -u nginx
sudo tail -n 100 /var/log/nginx/error.log

You can safely ignore errors that look like this:

2020/09/24 12:11:00 [error] 799#799: *254 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.106, server: tinypilot, request: "GET /socket.io/?EIO=3&transport=polling&t=NJ0uTPQ HTTP/1.1", upstream: "http://127.0.0.1:8000/socket.io/?EIO=3&transport=polling&t=NJ0uTPQ", host: "tinypilot", referrer: "http://tinypilot/"

Those usually just mean that TinyPilot's backend restarted while a user was connected.

Diagnostics

Troubleshooting keyboard/mouse issues

If TinyPilot fails to forward keystrokes, one way to debug is by checking if you can write to the keyboard interface from the command line:

# Should type "Hi" on the remote screen
echo -ne "\x20\0\xb\0\0\0\0\0" > /dev/hidg0 && \
  echo -ne "\0\0\xc\0\0\0\0\0" > /dev/hidg0 && \
  echo -ne "\0\0\0\0\0\0\0\0" > /dev/hidg0

When these commands hang indefinitely, it means that your USB-C cable does not work. It might not support USB OTG or it may be damaged. Swapping with a good cable should fix the problem.