Donkey Car Controller Quick Start Guide

Donkey Car Controller is a mobile app designed to provide a “commandless” user experience to get started with the Donkey Car. This article gives a step-by-step guide on how you can use this app.

Requirement

Before you start, you need the followings:

• A Donkey Car with Pi 4B (Jetson Nano is not yet supported)
• A Mobile phone with iOS or Android

Install the mobile app

Robocar Controller is available on both Apple’s App Store and Google Play Store. Simply install this app on your phone.

p.s.: We actually want to call this app “Donkeycar Controller” but need some further work here to comply with Apple rules as Donkeycar is a trademark.

Flash the SD card with pre-built image

1. Download Etcher
2. Download the latest pre-built image here
3. Flash the image into the SD card
4. Insert the card into the Pi

The mobile app only works with the pre-built OS image we made. This image contains a management software called Donkey Car Console, which is open source, and a lot of tweaks we put in the OS to support the features such as hotspot and low battery auto shutdown. There are a few caveats including security risks using this image. For details, please refer to the repo of this OS image on github. You can also find the username and password to login this image via SSH in the repo.

Connect your phone to the Hotspot

1. Turn on the Raspberry Pi
2. Wait until the green light stop blinking. This may take up to 2–3 minutes for the first time .The Pi will reboot 1–2 times until it is ready.
3. Go to the Wifi settings screen of your phone. You will see a hotspot named “donkey-xxxxxx” appear. Make sure you are connected to this hotspot before you leave the settings screen.

First Time Setup

1. Launch the app. Agree the terms when you use it for the first time.
2. The app will search for cars in the network. Your car should appear with an IP 192.168.50.1.
3. Tap the car shown. You will go to the first time setup screen.
4. Choose the controller type you are using. Most probably you will be using PCA9685. MM1 user please choose MM1.
5. Choose the country you are located. We need this information because wpa supplicant requires this information to comply with country specific Wifi rules. If an incorrect country is selected, unexpected wifi connection issue may occur.
6. Setup wifi connection. Search the wifi network nearby and select the wifi network you want the Pi to connect. Input the password and tap Done.
7. Review the settings. If everything is good, tap Done and the Pi will disable the hotspot and connect to the Wifi network. At this moment, you will see that your phone is disconnected from the hotspot because the Pi will disable it after successfully connect to the Wifi. Most probably your phone will fallback and connect to the original Wifi network it used to connect. Make sure your phone connects to the same network as the Pi.
8. You will be redirected back to the vehicle search screen. You should see your car appear with an IP assigned by your Wifi network.
9. Tap the car and go to the control panel of the car.

Here is a demo of the steps described above:

Calibration

After you have finished the first time setup, the first thing you may want to do is to calibrate your car. Tap into the calibration screen. Two tabs will be presented to config steering and throttle:

Calibration screen for PCA9685

For PCA9685, you can adjust the value of LEFT and RIGHT using the slide bar. When you change the value, the steering should change dynamically. You can even use the control knob to test whether the car could run a straight line.

The same goes for the FORWARD/REVERSE value on the throttle tab.

Drive

After calibration, tap the drive button to start driving the car. You will be asked whether you want to use the Virtual Joystick or the physical joystick. Let’s choose the virtual joystick for now. In addition, you will be asked to share your current location. The app add this location (lat,long) to the tub’s meta.json file.

The app will show your a Drive UI with two controlling knob. By default, the left is used to control the throttle and the right is used to turn left/right.

Use the recording button on the upper right corner to start recording. There is a counter on the upper section of the screen showing how many images it has recorded so far. Note that recording does not stop even when you stop moving. If the tub contains a lot of image that the car does not move, the model trained based on these image may not move properly as well. When you finished driving, tap the exit button on the upper left to quit the Drive UI. The app will present a driving summary to you:

Data

The data view shows you all the data(tubs) you have collected on the Pi.

When tap into any of these tubs, the app will make use of the donkey makemovie command to generate a video for you. You can also preview some of the images to check the quality. In addition, you can use the export function to save the video to your phone or generate a tarball of the tub and save it somewhere on the phone (or other cloud storage, e.g. Dropbox).

Train

As of today, we provide a free training service to the mobile app users.

To train a model, go to the train page from the control panel. You will see a list of previous train job you have submitted. At this stage, you should not see anything there because you haven’t started any training job yet. Tap the “+” button on the upper corner to train your first model.

You will be asked to select the tubs that you wish to train the model. Note that you can select multiple tubs in one go and the system will show you a summary before you hit the train button. The data will be uploaded to our server to start the training process.

Once the training is completed, the app will show you the training loss and accuracy graph. At the same time, the app will download the model to your car and you can start testing the model.

AutoPilot

There are two ways that you can start an autopilot. One way is to start the autopilot inside the train function. Like the screenshot shown above, you can start the autopilot directly from there. Another way is to use the “Autopilot” function from control panel. The app will list all models inside the Pi. In other words, you can copy models into the Pi and still use the app to start autopilot.

Once you are in the Drive UI, you are allowed to switch between “User” mode and “Autopilot” mode. Switch to autopilot and test the model. You can use the emergency stop button to quickly switch back to User mode.

p.s.: Autopilot — angle is not working yet

Advanced Configuration

The Doneky car software comes with a vast of configuration that you can experiment. We have included some of the popular options that you may want to change.

• Camera size
• Training configuration
• Drive train settings

To access this function, simply go to Settings->Vehicle Setting to check the options that you can change.

If you are an experienced Donkey Car user, this is just an UI that update myconfig.py easily.

Conclusion

This article shows you how you can use the Robocar Controller with the Donkey car software without typing a single command. We hope that it will simplify the and lower the technical barrier for everyone to try Donkey Car. Thanks for reading and get on Donkey Discord to tell us your experience using the app.

Future enhancements and bug reporting

If you have any suggestion or just want to report a bug, please feel free to submit an issue here.

Commercial Use

If you plan to use this app to make money, please follow the Donkey Car guideline and let us know too.