{"id":47327285,"url":"https://github.com/sourcebots/sbot_simulator","last_synced_at":"2026-03-17T19:32:01.382Z","repository":{"id":240577906,"uuid":"800150502","full_name":"sourcebots/sbot_simulator","owner":"sourcebots","description":"A simulator built around Webots to use the sbot library virtually","archived":false,"fork":false,"pushed_at":"2025-08-03T14:22:56.000Z","size":3367,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-03T14:36:48.488Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sourcebots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-13T19:50:13.000Z","updated_at":"2025-08-03T14:13:08.000Z","dependencies_parsed_at":"2024-05-19T22:24:05.522Z","dependency_job_id":"f343a959-cf2c-4331-b0a8-8ef21cf958e0","html_url":"https://github.com/sourcebots/sbot_simulator","commit_stats":null,"previous_names":["sourcebots/sbot_simulator"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/sourcebots/sbot_simulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebots%2Fsbot_simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebots%2Fsbot_simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebots%2Fsbot_simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebots%2Fsbot_simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sourcebots","download_url":"https://codeload.github.com/sourcebots/sbot_simulator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebots%2Fsbot_simulator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30629472,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T17:32:55.572Z","status":"ssl_error","status_checked_at":"2026-03-17T17:32:38.732Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-17T19:32:00.719Z","updated_at":"2026-03-17T19:32:01.362Z","avatar_url":"https://github.com/sourcebots.png","language":"Python","readme":"# sbot_simulator\nA simulator built around Webots to use the sbot library virtually.\n\n![sbot_simulator](assets/arena_overview.png)\n\n## Installation\n\nFirst, you need to install Webots. You can download the latest version from the [Webots website](https://cyberbotics.com/#download).\nAfter cloning the repository, you can install the simulator using the setup script.\n```bash\n./scripts/setup.py\n```\nThis script will create a virtual environment, install the required dependencies and set up Webots to use this virtual environment.\nAlternatively, you can install the simulator manually by following the steps below.\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\nYou will also need to set the Python paramter in the Webots preferences to point at the python binary in the virtual environment.\n\nIf you are intending to develop the API components of the simulator, you can install the sbot library in development mode as this is where the competitor facing API is defined.\n```bash\ngit clone https://github.com/sourcebots/sbot.git\npip install -e ../sbot\n```\n\n## Development\n\nWhen debugging the simulator, you can use the `WEBOTS_DEVICE_LOGGING` environment variable to set the logging level of the devices in the simulator.\nBy default, this is set to `WARNING`, setting it to `INFO` will log most device interactions and setting it to `DEBUG` will log all socket communication.\nThis can be achieved using the [runtime.ini file](https://cyberbotics.com/doc/guide/controller-programming#environment-variables) in Webots.\n\n### CI checks (linting and type checking)\nTo run the CI checks locally, you can install the development requirements and run the check commands.\n```bash\npip install -r dev_requirements.txt\npoe lint\npoe type\n```\n\nLinting errors can also be observed in real-time using the vscode extension charliermarsh.ruff after installing the development requirements.\n\n### Testing (__FUTURE FEATURE__)\n\nUnit and integration tests are grouped into two categories: those that don't require Webots and those that do.\nThe former can be run using the `poe test` command, while the latter can be run using the `poe webots-test` command.\n\n### Releases\n\nCI generates a release archive for each commit that can be viewed on the [actions page](https://github.com/sourcebots/sbot_simulator/actions/workflows/check.yml).\nThis archive contains the minimal files to install and run the simulator and a [user facing readme](assets/user_readme.md).\n\nTo generate a full release, create and push a tag with the version number.\nThe tag name will be used as the version number in the release archive.\nThe format of the tag should be `sroYYYY.X` where `YYYY` is the year and `X` is the release number for that year.\n\nTo generate a release locally, you can use one of the following commands. The version number is generated by git describe, so a local tag can be used to generate a clean version number.\n```bash\n# If you installed dev_requirements.txt\npoe release\n# Else\n./scripts/generate_release.py\n```\n\n## How it works\n\nThis repository itself does not provide a user-facing API, but instead uses the [sbot library](https://github.com/sourcebots/sbot) to provide the API.\nSince the sbot library is also used for the physical robots, this avoids the common issue of the simulator and physical robots having different APIs.\nThe simulator is built around Webots, a popular robotics simulator, and uses the Python API to interact with the devices in the simulator.\n\nThis interaction with Webots and sbot is achieved by using the pyserial library's ability to connect to a socket in the same way it would connect to a serial port. This allows the sbot library to interact with the devices in the simulator in the same way it would interact with the physical devices.\n\nThis mode of operation is enabled in sbot by setting the `WEBOTS_SIMULATOR` environment variable to `1`. Once this is set, the sbot library will use the value of the `WEBOTS_ROBOT` environment variable to determine the device URLs to connect to instead of attempting to discover boards connected to physical serial ports. The abstraction layers inside the simulator then follow the diagram below. The board wrapper classes implement an equivalent message handler to those in the physical board firmwares, while the device wrapper classes handle the Webots API calls to interact with the devices in the simulator.\n\n![simulator-sbot interface](assets/simulator-design.png)\n\nA few devices don't normally use a serial port but do interface with sockets to the simulator, these include the LED board, the camera interface and the sleep command. The way vision is handled in the simulator is by creating a new frame source in sbot that reads the camera image from the simulator and processes it in the same way as the physical camera, as shown in the diagram below.\n\n![vision design](assets/vision-interface.png)\n\nWhilst this does mean that a large amount of data is sent over the socket, the simulator is designed to run on the same machine as the sbot library, so this is not a significant issue.\n\nMetadata is handled by setting the `SBOT_METADATA_PATH` environment variable to a temporary directory. This directory acts like the metadata USB sticks in the physical robots, and has a `metadata.json` file containing the zone and mode of the robot.\n\n### World Design Notes\n\nTo simplify creating the arenas in the simulator, a set of proto files are used to define the arena layout.\nThe [arena proto](simulator/protos/arena/Arena.proto) takes the outer dimensions of the arena and generates a bounding box to contain the arena, along with a set of visual walls.\nThis can also be supplied with a texture for the floor to mark out staring and scoring zones.\n\nA [marker proto](simulator/protos/props/Marker.proto) provides a standard way to add markers to the arena, which can be used on walls and tokens.\nThis uses a plane to define the marker, without casting any shadows, or including its own bounding box.\n\n## Project Structure\n\nIn order to keep the released simulator tidy and easy to use, the project is split into a few key folders. The main simulator code is in the `simulator` folder which should only contain the code that is used to run the simulator. The `example_robots` folder contains a simple robot that can be used to start coding with the simulator and a keyboard controlled robot to explore the available sensors. Additionally the `scripts` folder contains the setup script and other utility scripts for the competitiors.\n\nAlongside these folders that are placed in the releases, the `assets` folder contains images and other resources that are used in the documentation. These are used to render an HTML page user facing readme that is included in the release archive.\n\nOf the the folders that are not included in the release, the `tests` folder contains the unit and integration tests for the simulator that don't require running webots and the `test_simulator` folder contains a separate webots world that is used to test the simulator.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcebots%2Fsbot_simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsourcebots%2Fsbot_simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcebots%2Fsbot_simulator/lists"}