{"id":44332417,"url":"https://github.com/bringauto/external-server","last_synced_at":"2026-02-11T10:10:01.709Z","repository":{"id":216112849,"uuid":"731213128","full_name":"bringauto/external-server","owner":"bringauto","description":"Fleet Protocol v2 External Server implementation in Python","archived":false,"fork":false,"pushed_at":"2026-02-10T10:43:06.000Z","size":852,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-02-10T15:52:52.216Z","etag":null,"topics":["fleet-protocol","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bringauto.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-13T15:26:14.000Z","updated_at":"2026-02-10T10:41:54.000Z","dependencies_parsed_at":"2024-08-23T09:59:13.330Z","dependency_job_id":"65e4c509-c5de-4ece-987d-9f6b15593720","html_url":"https://github.com/bringauto/external-server","commit_stats":null,"previous_names":["bringauto/external-server"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/bringauto/external-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Fexternal-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Fexternal-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Fexternal-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Fexternal-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bringauto","download_url":"https://codeload.github.com/bringauto/external-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Fexternal-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29331749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T06:13:03.264Z","status":"ssl_error","status_checked_at":"2026-02-11T06:12:55.843Z","response_time":97,"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":["fleet-protocol","python","python3"],"created_at":"2026-02-11T10:10:01.013Z","updated_at":"2026-02-11T10:10:01.697Z","avatar_url":"https://github.com/bringauto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# External Server\n\nThe External Server is a component of the [Fleet Protocol](https://github.com/bringauto/fleet-protocol). It communicates with an External Client, which is part of the [Module Gateway](https://gitlab.bringauto.com/bring-auto/fleet-protocol-v2/module-gateway).\n\nIt handles communication between a cloud instance and multiple cars registered under a single company.\n\n# Requirements\n\n- Python (version \u003e= 3.10)\n\n# Usage\n\n## Install dependencies\n\n### Submodules\n\nFirst, update the [fleet protocol](https://github.com/bringauto/fleet-protocol) submodule\n\n```bash\ngit submodule update --init lib/fleet-protocol\n```\n\n### Python packages\n\nInstall the required Python packages in a virtual environment by running the following (run pip3 install in the project root):\n\n```bash\npython3 -m venv .venv \u0026\u0026 \\\nsource .venv/bin/activate \u0026\u0026 \\\npip3 install -r requirements.txt\n```\n\n## Configure the External Server\n\nPrepare your config file for the External Server. The config file can be found in `config/config.json`.\n\nAs an example of a filled-up config file, see the `config/config.json`. Before running the server, update the `config/config.json` accordingly.\n\n### Server configuration\n\nSet up the logging, the MQTT connection parameters and company name and the External server behavior.\n\n- `logging` - contains the keys `console`and `file` for printing the logs into a console and a file, respectively. The `file` contains field `path` to set the (absolute or relative) path to the directory to store the logs. Both contain the following keys:\n  - `level` - logging level as a string (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). Case-insensitive.\n  - `use` - set to `True` to allow to print the logs, otherwise set to `False`.\n- `company_name` - used for MQTT topics name, should be same as in module gateway; only lowercase characters, numbers and underscores are allowed.\n- `mqtt_address` - IP address of the MQTT broker.\n- `mqtt_port` - port of the MQTT broker.\n- `mqtt_timeout` (in seconds) - timeout for getting a message from MQTT Client.\n- `timeout` (in seconds) - Maximum time amount between Status or Command messages and receiving corresponding responses.\n- `send_invalid_command` - sends command to Module gateway even if External Server detects invalid command returned from external_server_api; affects only normal communication.\n- `sleep_duration_after_connection_refused` - if the connection to Module Gateway was refused, the External Server will sleep for a defined duration before the next connection attempt proceeds.\n\n### Common modules\n\nOne of the last items in the config file is `common_modules`, represented by key-value pairs. The key is the module ID (a module number), the value contains following\n\n- `lib_path` (required) - path to module shared library (`*.so`).\n- `config` (optional) - module specific configuration, any key-value pairs will be forwarded to module implementation init function. When empty or not provided, empty configuration is forwarded to the init function of module.\n  \u003e [!WARNING]\n  \u003e A common module will be used for all cars. No such module can be defined in the car configuration.\n  \u003e See the `config/config.json` for an example of modules configuration.\n\n### Cars\n\nThe last item in the config file is `cars`, represented by key-value pairs. The key is the name of the car, the value is a dictionary containing car-specific modules keyed as `specific_modules`.\n\nThe structure of the `specific_modules` is the same as the `common_modules` structure.\n\nSee the `config/config.json` for an example of car configuration.\n\n\u003e [!WARNING]\n\u003e Configuring a module with the same ID both in `common_modules` and `specific_modules` is invalid and the server will not start.\n\n\u003e [!IMPORTANT]\n\u003e For each car, at least one module has to be defined, either in `common_modules` or `specific_modules`.\n\n## Start the External Server\n\nAfter configuration and installation of the dependencies, run External Server with this command:\n\n```bash\npython3 -m external_server \u003cconfig\u003e [--tls] [--ca \u003cstr\u003e] [--cert \u003cstr\u003e] [--key \u003cstr\u003e]\n```\n\n- `\u003cconfig\u003e` = path to the config file\n- `--tls` = tls mqtt authentication\n\nFollowing arguments are used if argument `tls` is set:\n\n- `--ca \u003cstr\u003e` = path to ca certification\n- `--cert \u003cstr\u003e` = path to cert file\n- `--key \u003cstr\u003e` = path to key file\n\n## Build Standalone Package (.pyz)\n\nThe External Server can be packaged as a standalone `.pyz` file using [shiv](https://github.com/linkedin/shiv). This is useful for deployment or integration testing.\n\n### Prerequisites\n\n- Complete the [Install dependencies](#install-dependencies) steps\n- Install shiv: `pip install shiv`\n\n### Build\n\n```bash\nshiv -e external_server.__main__:main -o external_server.pyz . -r requirements.txt --compressed\n```\n\nThis creates `external_server.pyz` which bundles the application with all dependencies. Run it with:\n\n```bash\npython3 external_server.pyz \u003cconfig\u003e [--tls] [--ca \u003cstr\u003e] [--cert \u003cstr\u003e] [--key \u003cstr\u003e]\n```\n\n# Unit tests\n\n## Necessary steps before testing\n\n### Requirements\n\n- [Requirements](#requirements)\n- CMLIB: https://github.com/cmakelib/cmakelib\n\n### Install the external server package\n\nDo the steps from the [Install dependencies](#install-dependencies) section.\n\nInstall the package in editable mode and install test requirements (assuming you already installed the requirements for the server):\n\n```bash\npip install -e .\npip install -r tests/requirements.txt\n```\n\nUpdate submodules\n\n```bash\ngit submodule update --init --recursive\n```\n\n### Install the shared library\n\nCompile a shared library for the [Example Module](https://github.com/bringauto/example-module/). This requires\n\n- the [example-module](https://github.com/bringauto/example-module/) cloned as a submodule in the `tests/utils` directory.\n\nRun the following\n\n```bash\npushd tests/utils/example_module \u0026\u0026 \\\nmkdir -p _build \u0026\u0026 \\\ncd _build \u0026\u0026 \\\ncmake .. -DCMLIB_DIR=\u003cpath-to-cmakelib-dir\u003e \u0026\u0026 \\\nmake\npopd\n```\n\ncmakelib directory is absolute path to this repo root directory.\n\n## Running the tests\n\nIn the root folder, run the following\n\n```bash\npython -m tests [-h] [PATH1] [PATH2] ...\n```\n\nEach PATH is specified relative to the `tests` folder. If no PATH is specified, all the tests will run. Otherwise\n\n- when PATH is a directory, the script will run all tests in this directory (and subdirectories),\n- when PATH is a Python file, the script will run all tests in the file.\n\nThe `-h` flag makes the script display tests' coverage in an HTML format, for example in your web browser.\n\n# Docker\n\nThe External Server is ready to use with Docker. You can build a Docker image with `docker build .` in this directory. The Dockerfile also describes compiling these Bringauto modules:\n\n- module 1 - Mission module,\n- module 2 - IO module.\n\nThese compiled modules are inserted into the image and are ready to use with the External Server in a Docker container.\n\nThe External Server can also be used with Docker Compose. In the `docker-compose.yml` is example of External Server service, which can't be used alone and should be inserted into another `docker-compose.yml` with MQTT service and defined network (the [etna](https://github.com/bringauto/etna) is an example). This specific example assumes that MQTT broker is service named `mosquitto` and defined network is `bring-emulator`.\n\n# Development\n\n## Type checking\n\nTo allow for type checking of the classes from compiler protobuf of Fleet Protocol, run the code below.\n\n\u003e [!WARNING]\n\u003e After you update the Fleet Protocol submodule, ensure that all imports in the generated files are correct. The generated files are located in `lib/fleet-protocol/protobuf/compiled/python/fleet_protocol_protobuf_files`.\n\n```bash\npushd lib/fleet-protocol/protobuf \u0026\u0026 \\\nfind ./definition -name \"*.proto\" -exec protoc -I=./definition --python_out=./compiled/python/fleet_protocol_protobuf_files --pyi_out=./compiled/python/fleet_protocol_protobuf_files {} +\npopd\n```\n\nThen reinstall the requirements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbringauto%2Fexternal-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbringauto%2Fexternal-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbringauto%2Fexternal-server/lists"}