Bots2D

Bots2D is a C++ framework for simulating robotics in 2D, which provides you with boilerplate and robotics assets to help you quickly set up your simulation. You can read more about it here.

<img src="docs/images/sumobot_feature.gif"> <img src="docs/images/line_follower_feature.png">

Background

There are several projects out there for simulating robotics (Gazebo, Webots, V-REP, AirSim, etc.). These have advanced toolsets and are great at realistic simulations, but come at the cost of a lot of overhead, which is tedious and overkill for simpler simulations.

Despite 2D simulators being useful and easier to implement, few well-established projects exist. It's fairly straightforward to develop one from scratch given the available open-source rendering/physics libraries, but it still takes quite a bit of work, enough to motivate this framework. And if we are several who use the same framework, we can assemble a larger set of reusable robotics assets.

Features

• C++
• Linux and Windows
• Physics based on Box2D
  • Top-view and side-view
• Lightweight rendering using OpenGL, GLFW, GLAD and ImGui
  • Basic shapes, Texture, Sprite animation
• Robotics assets (so far):
  • Complete robots
    • Sumobot with custom dimensions, wheels, sensors, speed, acceleration, etc.
    • Line-follower with custom dimensions, wheels, sensors, speed, acceleration, etc.
  • Sensors
    • Range sensor
    • Line detector
  • Actuators
    • Basic DC-motor model with tuneable acceleration and speed characteristics
  • Playgrounds
    • Sumobot dohyo with customizable radius
    • Customizable line follower path
  • It's easy to create new assets...
• Language binding ("Software-in-loop")
  • Controller code can be written in C (easy to transfer to a real MCU)
• Customizable controller/physics update rate
  • ~60-2000 Hz (or more depending the host computer)

Limitations

• Not built or tested on macOS (OpenGL is deprecated on macOS)
• Physics
  • Object dimensions limited to 0.01-1m
    • As a consequence of Box2D being limited to 0.1-10m
    • The physics scale factor can be changed, but the span between min and max is still limited
  • Roughly approximated top-view physics
    • Sets Box2D gravity to 0 and uses b2FrictionJoint for friction.
• Simulation speed fixed to real time
  • No fast-forwarding or slowmotion.
• Rendering
  • No z-indexing, so you must create objects in the order you want them rendered.
• No drag-and-drop GUI
  • Everything is set up through code.
• Performance
  • Not optimized for complex simulations (involving many objects)

Getting started

There is a testapp under testapp/, which shows you how to use the framework. It contains a set of scenes based on the existing robotics assets (under assets/).

Clone

Bots2D depends on other git projects checked out at specific commits. These are included as git submodules under external/. To clone the repo (including all submodules), run:

git clone --recursive -j8 https://github.com/artfulbytes/bots2d

If you already accidently cloned the repo non-recursively, you can get the submodules with:

git submodule update --init

Build

Bots2D is built with CMake. Look at testapp/ for an example of how to use it in your application.

Build testapp on Linux

On Ubuntu 20.04, you may have to install the following packages:

sudo apt install mesa-common-dev \
libxi-dev \
libxcursor-dev \
libxinerama-dev \
libxrandr-dev \
libx11-dev

Then run:

cd testapp/
mkdir build
cd build
cmake ..
cmake --build .
run build/bots2d_testapp

Build testapp on Windows

Tested with Visual Studio 2019:

1. Open local folder and select bots2d/testapp
2. After VS has loaded the project, right-click on CMakeLists.txt in the solution
   explorer and set it as startup item.
3. Start Debugging (F5)

Folder structure

| Folder name | Description | | ------------| -------------------------------------------------------------| | assets | Reusable robotics objects and textures | | docs | Documentation | | external | External dependencies | | src | Bots2D implementation and header files | | testapp | An example/test application with test scenes | | tools | Standalone helper tools/scripts |

Documentation

Bots2D is documented with Doxygen. You can generate the documentation with:

doxygen docs/Doxyfile

to docs/. You can also access it online here. If you want to push new updates to the online version, you should push the changes to the gh-branch (not master).

There is also a lenghty blog post about Bots2D here.

Known issues

• Rendering is slightly off (probably because of rounding error)
  • Physics is fine, but two objects next to each other are rendered with a small gap in-between.
• Rendering movement is jittery when the physics rate < 2x rendering rate
  • No graphics interpolation

Troubleshooting

• Incorrect OpenGL version (Linux)
  • Check version in console output
  • "export MESA_GL_VERSION_OVERRIDE=3.3"
• "RandR headers not found; install libxrandr development package"
  • GLFW requires xorg-dev liblu1-mesa-dev
  • On Ubuntu, run "sudo apt install xorg-dev libglu1-mesa-dev"

Contributing

If you modify or add something, you are encouraged to submit a pull request. In that case, make sure you also create a corresponding test scene in the testapp.

Dependencies

Bots2D depends on the following libraries:

| Name | Description | License | | ------| --------------------------------| ------------| | Box2D | Used for 2D physics | MIT | | GLFW | Used for window management | zlib/libpng | | ImGui | Used for GUI overlay | MIT | | stb | Used for image loading | MIT | | GLM | Used for vector math | MIT |

They are included (untouched) as git submodules under external/.

Credits

| Name | | | ---- | ---- | | The Cherno | Some of the rendering code stem from his YouTube tutorials. | | iforce2d | Very useful Box2D tutorials |