Start Script Debugging

As the software is evolving, sometimes the way the system is started has to be adjusted. We try to keep this to an absolute minimum. If a start script doesn't work any more (the system does not start at all or not completely), it is relatively straightforward to debug.

The autostart scripts in the repository are maintained by the community, however, if you have custom scripts on your microSD card, you need to update them from time to time as the software evolves.

Please read and understand the documentation for the system startup first!

Generic Debugging Tips


The firmware has the tests command. tests help does list all tests, and they are great to isolate issues. E.g. tests sensors tests the sensors. Individual drivers also have tests, and most have a status command (e.g. lsm303d status).

Custom Script on a microSD

There are a few hooks to execute a custom app. Make sure to choose the least invasive option to minimize the effort for you maintaining it.

Read this before debugging and make sure you are using the right approach

  • If you just need to set a few parameters or environment variables, use the CONFIG_FILE, which should be placed at /etc/config.txt on the microSD. It can be used to overwrite platform parameters as descibed here.
  • If you want to start additional apps, use the EXTRAS_FILE which should be put at /etc/extras.txt on the microSD card. It gets executed after all other essential applications have been started.
  • If you really need to do a completely custom startup, put the RC_FILE in the folder /etc/rc.txt. This approach is only for people who know what they are doing!


This debugging example is for the rc.txt, but it applies to the other hook files similarly.

  1. Rename the file on the card, e.g. if it is the /etc/rc.txt rename it to /etc/rc_test.txt.
  2. Put the card back in and boot.
  3. Connect to the terminal via the USB serial connection.
  4. Execute the script manually: sh /fs/microsd/etc/rc_test.txt
  5. This is now the critical point: Observe the script startup, and note where it fails. Check that your syntax and arguments are correct. Fix anything that is not right on the microSD script, and repeat the procedure until it boots successfully.
  6. TIP: To identify the lines that fail, put every few lines an echo. This will tell you exactly where the script aborted.
    • echo “here1”, then a few lines later
    • echo “here2”, and so on.

And again, make sure you need a custom startup script at all.

Translations of this page:

Quick Links

QR Code: URL of current page