Handling - Duckiebot DB21#

What you will need

What you will get

Knowledge on standard protocols to turn on, turn off, charge, and update the Duckiebattery software version on a DB21 robots;

Note

The box above contains important information on the requirements. Make sure to read and follow them before proceeding.

Note

In this manual, we use DB21 to refer to any version of the Duckiebot with prefix DB21, such as, DB21J, DB21M, etc.

Duckiebot DB21 handling tutorial video#

How to charge a DB21#

To charge your Duckiebot, follow these steps:

  • Plug in the charging cable to the free microUSB port on the HUT.

Note: to minimize mechanical stress on the HUT we recommend plugging in the charging cable once, and leaving the USB port end free to plug and unplug from charging instead. You can arrange the cable under the DB21 top plate during operations for cable management.

  • Plug in the charger to a 5V 2A source.

    Note

    the battery can draw up to 2A. Feeding a higher amperage will not be a problem, but wrong voltage will send the battery in protection mode.

  • If the Duckiebot is turned on when charging, a battery charge indicator will appear on the top right of the screen. If the Duckiebot is turned off, the LEDs will turn on. In both cases, a small LED on the HUT near the charger port will turn green, indicating incoming power.

How to power off a DB21#

Warning

The proper shutdown protocol for a DB21 requires having the Duckiebattery software version 2.0.0 or newer. To check the version of your battery, follow the instruction to “Verify current battery version” on How to update a Duckiebattery.

Make sure the Duckiebot has completed the booting process. You can verify this by checking the “Status” after running dts fleet discover on your laptop: a green Ready message will indicate that the Duckiebot has completed the booting process.

There are three methods to power off a DB21:

  1. Using the top button (preferred):

    1. Press the top button (not the battery button) for 5 seconds and release;

    2. What to expect:

      1. The top button will blink for 3 seconds;

      2. The Duckiebot front and back LEDs turn off;

      3. In about 10 seconds, the on-board computer and the fan will shut down;

    3. Troubleshooting: If the display just switched to the next page and the top button did not blink, try again and push harder on the top button during the 5 seconds;

  2. Using dts:

    1. dts duckiebot shutdown ![ROBOT_NAME]

    2. What to expect:

      1. In about 10 seconds, the on-board computer and the fan will shut down;

      2. If the charging cable is not attached, the front and back LEDs will also turn off;

  3. Through the Duckiebot dashboard:

    1. Open a browser

    2. Navigate to http://![ROBOT_NAME].local

    3. In the Top-Right corner, click on the Power options, and choose “Shutdown”. Then confirm the action.

    4. What to expect:

      1. In about 10 seconds, the on-board computer and the fan will shut down;

      2. If the charging cable is not attached, the front and back LEDs will also turn off;

Warning

The following “hard” power shutdown should be only be used if the three methods above failed to shut down the Duckiebot, as it might lead to software corruption.

As a last resort, one could still perform a “hard” power shutdown of the DB21:

  • ssh duckie@![ROBOT_NAME].local sudo poweroff;

  • Unplugging the microUSB cable from the port marked as 5Vraspi on the HUT;

How to power on a DB21#

To power on a DB21 robot, press the button on the battery once.

The Duckiebot LEDs, as well as the on-board computer LED will turn on.

After a few seconds, the Wi-Fi dongle will start blinking. The Duckiebot LEDs will then turn to a steady white color, followed by the button and screen on the top plate powering on, as shown in the tutorial video above.

How to SSH to the Duckiebot#

Next, let us try and log in onto our robot using the SSH (Secure Shell) protocol. We can do so by running the command,

ssh [email protected]

The default password is quackquack.

How to update a Duckiebattery#

To update the software running on the microcontroller in the Duckiebattery, or just checking its current version, use the following instructions.

Important:

  1. Before the battery upgrade, please make sure the battery has at least 15% of charge.

  2. Run all the following commands on the desktop/laptop

Make sure the Duckiebot is powered on and connected to the network. You can verify the latter by launching, e.g., dts fleet discover and finding that your Duckiebot is on the list.

  1. Please update the duckietown-shell utility:

    1. pip3 install --user --upgrade --no-cache-dir duckietown-shell

    2. dts update

    3. dts desktop update

  2. Update the Duckiebot:

    1. dts duckiebot update ![ROBOT_NAME]

  3. Reboot the Duckiebot:

    1. ssh duckie@![ROBOT_NAME].local sudo reboot

    2. Wait until the Duckiebot reboots and the display shows information (especially about the battery).

    3. You could verify the battery related software is up and running by checking whether the display reacts correctly to charging states when a charging cable is plugged in and unplugged.

  4. Upgrade the battery firmware:

    1. dts duckiebot battery upgrade ![ROBOT_NAME]

      1. Note: When prompted to “double-click” on the battery button, make sure to quickly click twice the battery button.

      2. Note: Do not worry if you are unsure if you actually pressed the button twice or not, as the battery upgrade process will verify this.

      3. Follow the instructions in the terminal.

    2. If the command finished with the error: SAM-BA operation failed INFO:UpgradeHelper:An error occurred while flashing the battery. ERROR:dts:The battery reported the status 'GENERIC_ERROR', please try flashing again with: dts duckiebot battery upgrade --force ![ROBOT_NAME]

    3. If the command finished with any other error: single press the battery button, and start from step 3 again one more time. If there are still errors, please report on StackOverflow.

  5. Prepare for post-upgrade checks

    1. If the battery indicates the charging states correctly, and shows the percentage number normally, proceed to step 6

    2. If the display shows “NoBT” (No battery detected), then single press the battery button, and run:

      1. ssh duckie@![ROBOT_NAME].local sudo reboot

      2. Wait for the reboot (as described in step 3)

      3. Then proceed to step 6

  6. Verify current battery version:

    1. Method 1:

      1. dts duckiebot battery check_firmware ![ROBOT_NAME]

      2. Verify the battery version should be 2.0.2 or newer

    2. Method 2:

      1. Open a browser window

      2. Navigate to http://![ROBOT_NAME].local/health/battery/info

      3. Verify the battery version should be 2.0.2 or newer

Troubleshooting

SYMPTOM

The power button on top does not shut off the Duckiebot.

RESOLUTION

The power button needs to be held for three seconds and then released. If this still does not work, run dts duckiebot update <your_robot> and then use dts duckiebot reboot <your_robot>. You may also need to re-flash your HUT following the procedure described in Debug - Re-flash Microcontroller if you have not already.

Troubleshooting

SYMPTOM

My Duckiebot has a very low battery charge and is stuck in a boot cycle.

RESOLUTION

Unplug all cables from the HUT except port # that is used to charge the battery. Allow the battery to charge for at least 5 hours before plugging all cables back in their nominal positions.

How to update a HUT#

Instructions on how to flash a Duckietown HUT board can be found here.

Note

Reflashing a HUT is rarely needed. A notable exception is for HUT version 3.15 which comes with DB21s. The HUT version can be read on the board itself.