BlueAndi / ZumoHALWebots

Zumo C++ hardware abstraction layer for the Webots simulation.

ZumoHALWebots

Hardware abstraction layer for the Pololu Zumo robot (see https://www.pololu.com/category/129/zumo-robots-and-accessories) in the Webots simulation.

Table of content

• Architecture
  • The Principle
  • Detail
• How to integrate the library?
  • Example with recommended flow
• Requirements to your application
  • General
  • Buttons
  • Buzzer
• Used Libraries
• Issues, Ideas And Bugs
• License
• Contribution

Architecture

The Principle

Detail

See details of the Webots library classes in the Webots reference manual.

How to integrate the library?

1. Add it to the platformio.ini in your environment to the lib_deps section:

   lib_deps =
       BlueAndi/ArduinoNative @ ~0.1.0
       BlueAndi/ZumoHALWebots @ ~0.1.1
   

2. Add the header include search directories to the build flags.

   build_flags =
       -I./lib/Webots/include/c
       -I./lib/Webots/include/cpp
   

3. Add to your platformio environment the following scripts.

   extra_scripts =
       pre:$PROJECT_LIBDEPS_DIR/$PIOENV/ZumoHALWebots/scripts/create_webots_library.py
       pre:$PROJECT_LIBDEPS_DIR/$PIOENV/ZumoHALWebots/scripts/copy_sounds.py
       post:$PROJECT_LIBDEPS_DIR/$PIOENV/ZumoHALWebots/scripts/copy_webots_shared_libs.py
   

   • create_webots_library.py: Generates the Webots library under the /lib folder, derived from your local Webots installation.
   • copy_sounds.py: Copies the sound files used for sound generation.
   • copy_webots_shared_libs.py: Copies the Webots shared libraries to the local platformio environment specific build folder .pio/build/<environment> as post-build step. They are required by the exectuable.
4. Integrate the following main flow to your main.cpp.
5. Consider the requirements to your application.

Example with recommended flow

See minimal example.

Requirements to your application

General

• REQ-1 The SimTime::step() shall be called for one single simulation time step.
• REQ-2 The SimTime::step() shall be called once before the Arduino::setup() is called.
• REQ-3 The SimTime::step() shall be called once before the Arduino::loop() is called periodically.
• REQ-4 The Keyboard::getPressedButtons() shall be called once before the Arduino::loop() is called periodically.
• REQ-7 The application functions, which are running in the Arduino::loop() shall not block (cooperative behaviour).

Buttons

• REQ-5 The application shall never wait in an loop until a button gets released or pressed.

Buzzer

• REQ-6 If the application waits until Buzzer::isPlaying() returns true, the application shall call Buzzer::process() and delay(1U) in the loop.
  • INFO:
    1. The sound is stopped by the Buzzer::process(). Without stopping it, the Buzzer::isPlaying() will always return true.
    2. The simulation time must be stepped forward, otherwise during Buzzer::process() the sound won't stop. The workaround is here to use a delay() which internally ticks the simulation time.

Used Libraries

Library	Description	License
ArduinoNative	The Arduino for native environment.	MIT
ArduinoJson	JSON library for Arduino and embedded C++. Simple and efficient.	MIT
Webots	Webots physical simulation C++ API.	Apache 2.0
ZumoHALInterfaces	The Zumo C++ HAL interfaces.	MIT

Issues, Ideas And Bugs

If you have further ideas or you found some bugs, great! Create a issue or if you are able and willing to fix it by yourself, clone the repository and create a pull request.

License

The whole source code is published under the MIT license. Consider the different licenses of the used third party libraries too!

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions.