Getting Started

To get started with the gym API you need to do the following setup :

1. Make sure you have python 3.11 installed, other versions might or might not work but 3.11 has been tested.

2. Install system dependencies :

   sudo apt-get install -y libturbojpeg

3. Install python dependencies :

   pip install gymnasium numpy dtps-http

   Install duckietown-sdk using the ente branch :

   pip install git+https://github.com/duckietown/duckietown-sdk.git@ente

   Install the duckiematrix gym :

   pip install git+https://github.com/duckietown/gym-duckiematrix.git

4. Launch the duckiematrix using dts :

   dts matrix run --standalone --embedded --no-tutorial --map loop

   This command launches the engine locally (--standalone), using the default maps (--embedded), skips the tutorial pop-up (--no-tutorial) and uses the default map called loop (--map loop).
   It is possible to specify different configurations (eg: load different maps), see the documentation for more details.

5. Create the gym environment, optionally you can use gymnasium built-in wrapper TimeLimit if you want to impose a maximum number of steps on a trajectory.
   The following code example creates the gym environment, wraps it using TimeLimit and executes a predefined number of random rollouts :

   from gymnasium.wrappers import TimeLimit
   from gym_duckiematrix.DB21J import DuckiematrixDB21JEnv
   
   def execute_random_rollout(env):
       obs, info = env.reset()
       done = False
       while not done:
           action = env.action_space.sample()
           obs, reward, terminated, truncated, info = env.step(action)
           done = terminated or truncated
   
   env = TimeLimit(
       DuckiematrixDB21JEnv(
           entity_name="map_0/vehicle_0",
           out_of_road_penalty=-10.0,
           headless=False,
           camera_height=480,
           camera_width=640
       ),
       max_episode_steps=100,
   )
   nb_random_rollouts_for_testing_purposes = 2
   try:
       for _ in range(nb_random_rollouts_for_testing_purposes):
           execute_random_rollout(env)
   except Exception as e:
       print("An error occurred:", e)
   finally:
       env.close()

Note : The headless parameter controls whether a graphical window opens to display frames in real time during execution.
Setting it to False disables the GUI entirely (e.g: ideal for running code on a cluster).
Setting it to True enables visualization, which is useful for debugging but may slow down execution.

The default reward function encourages the duckie to move forward along the lane and penalizes deviations from the lane center.
If lane lookup fails, the agent receives an out-of-road penalty and a termination signal.
Feel free to define your own reward function by sub-classing DuckiematrixDB21JEnv and write your own reward_fn.

If you do not want to impose a maximum number of steps, then simply create the environment without the TimeLimit wrapper :

env = DuckiematrixDB21JEnv(
    entity_name="map_0/vehicle_0",
    out_of_road_penalty=-10.0,
    headless=False,
    camera_height=480,
    camera_width=640
)

---

Details.

See details here.

Template for pure Python libraries in Duckietown

This template provides a boilerplate repository for developing Python libraries in Duckietown.

We have the following features:

• Unit-tests using Nose.
• Building/testing in Docker environment locally.
• Integration with CircleCI for automated testing.
• Integration with CodeCov for displaying coverage result.
• Integration with Sphinx to build code docs. (So far, only built locally.)
• Jupyter notebooks, which are run also in CircleCI as tests.
• Version bump using Bumpversion.
• Code formatting using Black.
• Command-line program for using the library.

Anatomy of the repo

This repository describes a library called "duckietown_pondcleaner" and there is one command-line tool called dt-pc-demo.

Warning: Do not remove files/features just because you don't understand. Ask instead. See: Chesterson's fence.

Meta-files

• .gitignore: Files ignore by Git.

• .dtproject: ...

• .bumpversion.cfg: Configuration for bumpversion

• Makefile: ...

Python packaging

• requirements.txt: Contains the pinned versions of your requirement that are used to run tests.

• MANIFEST.in: Deselects the tests to be included in the egg.

• setup.py: Containes meta information, definition of the scripts, and the dependencies information.

Python code

• src/ - This is the path that you should set as "sources root" in your tool

• src/duckietown_pondcleaner: Contains the code.

• src/duckietown_pondcleaner/__init__.py: Contains the __version__ library.

• src/duckietown_pondcleaner_tests: Contains the tests - not included in the egg.

Docker testing

These are files to build and run a testing container.

• .dockerignore: Describes what files go in the docker container.

• Dockerfile: ...

Sphinx

• src/conf.py: Sphinx settings

• src/index.rst: Sphinx main file

• src/duckietown_pondcleaner/index.rst: Documentation for the package

Coverage

• .coveragerc: Options for code coverage.

Notebooks

• notebooks: Notebooks that are run also as a test.

• notebooks-extra: Other notebooks (not run as test)

• notebooks/*.ipynb: The notebooks themselves.

---

---

Cloning/forking/customizing

Fork this repository

Use the fork button in the top-right corner of the Github page to fork this template repository.

Create a new repository

Create a new repository on Github while specifying the newly forked template repository as a template for your new repository.

Fill in the blanks

Build a library by following these steps:

• Clone the newly created repository;
• Place your Python packages inside src/;
• List the python dependencies in the file dependencies.txt;
• Update the appropriate section in the file setup.py;

Make sure that there are no other remains:

grep -r . pondcleaner

Update the branch names in README.md.

Other set up (for admins)

The following are necessary steps for admins to do:

1. Activate on CircleCI. Make one build successful.

2. Activate on CodeCov. Get the CODECOV_TOKEN. Put this token in CircleCI environment.

---

---

How to use this library

Test the code

Test the code using Docker by:

make test-docker

This runs the test using a Docker container built from scratch with the pinned dependencies in requirements.txt. This is equivalent to what is run on CircleCI.

To run the tests natively, use:

make test

Development

We assume you have already setup a Python virtual environment.

Then we suggest you run:

python setup.py develop

This will install the library in an editable way (rather than copying the sources somewhere else).

If you don't want to install the deps, do:

python setup.py develop  --no-deps

For example, this is done in the Dockerfile so that we know we are only using the dependencies in requirements.txt with the exact pinned version.

Adding tests

To add another tests, add files with the name test_*py in the package duckietown_podcleaner_tests. The name is important.

Tip: make sure that the tests are actually run looking at the coverage results.

Notes on using the notebooks

Always clean the notebooks before committing them:

make -C notebooks cleanup

If you don't think you can be diligent, then add the notebooks using Git LFS.

Releasing a new version

Updating the version

The first step is to change the version and tag the repo. DO NOT change the version manually; use the CLI tool bumpversion instead.

The tool can be called by:

make bump    # bump the version, tag the tree

If you need to include the version in a new file, list it inside the file .bumpversion.cfg using the syntax [bumpversion:file:<FILE_PATH>].

Releasing the package

The next step is to upload the package to PyPy. We use twine. Invoke using:

make upload  # upload to PyPy

For this step, uou need to have admin permissions on PyPy.