Developing evcc requires Go Node and Vite+. We recommend VSCode with the Go, Oxc and Vue extensions.
Alternatively, if you use VS Code and devcontainers, you can use the "Dev containers: Clone repository in container volume" action. This will create a devcontainer with the required toolchain and install the prerequisites as explained below. Wait until the startup log says "Done. Press any key to close the terminal." and check for any errors.
We use linters (golangci-lint, oxlint/oxfmt via Vite+) to keep a coherent source code formatting. It's recommended to use the format-on-save feature of your editor. You can manually reformat your code by running:
make lint
make lint-uiThe software supports a massive amount of different devices (charger, meter, vehicle, tariff) that are defined by templates.
A template can use the plugin system (preferred) for communication with the device or reference a dedicated Go implementation.
All bundled templates are located in the /templates/definition directory.
If you want to add a new plugin we recommend looking at existing, similar implementations for reference. When your template requires Go code you have to build the project from source (see instructions below). Otherwise you can use the evcc binary and point it to your new template file for testing.
evcc --template-type charger --template new-charger-template.yamlBesides the actual device configuration, templates contain meta-data like product name, manufacturer, instructions how to configure the device to work with evcc.
On release, this data is extracted and pushed to the evcc-io/docs repository to keep the documentation in sync. You can verify the generated meta-data by running:
make docsThis will write the documentation-relevant data to /templates/docs.
Install prerequisites (once):
make install-ui
make installBuild and run:
make
./evccOpen UI at http://127.0.0.1:7070
To run without creating the evcc binary use:
go run ./...
To compile a version for an ARM device like a Raspberry Pi set GO command variables as needed, eg:
GOOS=linux GOARCH=arm GOARM=6 makemake docker DOCKER_IMAGE=my/docker DOCKER_TAG=0815Releases are cut by pushing a MAJOR.MINOR.PATCH tag. Any other tag is ignored.
Feature releases (0.313.0) must be tagged on master. The release workflow
rejects a feature tag that is not reachable from master.
Bugfix releases (0.313.1) may be tagged on any branch. That allows servicing
an older release line without shipping everything that has landed on master
since. Only the newest release moves the latest pointers, so a bugfix release
of an older line publishes its artifacts, but leaves the evcc/evcc:latest
docker tag, the homebrew formula, the GitHub latest release, the hassio addon
and the demo instance untouched.
To move a merged pull request onto a release branch, comment /backport on it.
The pull request has to carry the bug label and must not be marked (BC),
only non-breaking bugfixes are backported.
The commit is cherry-picked onto the branch of the next bugfix release, e.g.
release/0.313.1, and a pull request is opened against it. The branch is
created at the newest tag of that line if it does not exist yet. Pass a branch
name, /backport release/0.312.2, to service an older line.
Releasing a bugfix deletes its release branch, since the tag is the branch tip and everything on it has shipped. A branch that received further backports after the tag is kept.
To debug a local evcc build in VS Code, add the following entry to your launch.json.
You can adjust the referred configuration as needed to e.g. use your live configuration.
{
"name": "Launch evcc local build with demo config",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}",
"args": ["-c", "${workspaceFolder}/cmd/demo.yaml"],
"cwd": "${workspaceFolder}",
},For frontend development start the Vue toolchain in dev-mode. Open http://127.0.0.1:7071/ to get to the live reloading development server. It pulls its data from port 7070 (see above).
vp install
vp run devStart the backend with --disable-auth when checking the configuration UI of a
throw-away instance. Without it the UI asks for an administrator password first.
./evcc --config tests/config-with-tariffs.evcc.yaml --disable-authWe're using storybook to develop and visualize UI components in different states. Running the command below will open your browser at http://127.0.0.1:6006/.
vp run storybookWe use Playwright for end-to-end integration tests. They start a local evcc instance with different configuration yamls and prefilled databases. To run them, you have to do a local build first.
make ui build
vp run playwrightSince we don't want to run tests against real devices or cloud services, we've build a simple simulator that lets you emulated meters, vehicles and loadpoints. The simulators web interface runs on http://localhost:7072.
vp run simulator
Run an evcc instance that uses simulator data. This configuration runs with a very high refresh interval to speed up testing.
make ui build
./evcc --config tests/simulator.evcc.yaml
evcc has a large German-speaking user base, but we want to be open and accessible to everyone in the global community. To balance these needs:
- Pull Requests
- 🇬🇧 English required
- Issues
- 🇬🇧 English recommended
- 🇩🇪 German acceptable to start, must switch to English after first English comment
- GitHub Discussions
- 🇬🇧 🇩🇪 Both English and German allowed
💬 Non-German speakers: We strongly encourage you to ask participants to switch to English. For pull requests, we have a language check bot that does this automatically.
Thank you all for helping make evcc accessible! 🌍
AI tools can be valuable aids for writing code, documentation, and creating issue reports. We welcome their use as part of the development process.
When submitting AI-assisted contributions, keep these principles in mind:
- Understanding: Fully understand all changes and be prepared to answer questions about them.
- Human-written intent: Write issue descriptions, PR explanations, and commit messages in your own words. Keep them clear and concise, not lengthy generated text.
- Value: Ensure contributions justify the review effort required from maintainers.
- Prior consensus: Only open a PR if there is a related issue or discussion where the team has indicated a positive tendency toward the proposed change. Link to it in your PR description.
Contributors remain responsible for their work regardless of which tools were used to create it.
Contributions that appear to violate these principles will be closed with the following comment:
This contribution does not appear to meet our [AI contribution guidelines](https://github.com/evcc-io/evcc/blob/master/CONTRIBUTING.md#ai-generated-content).
evcc already includes many translations for the UI. We're using Weblate to maintain translations. Feel free to add more languages or verify and edit existing translations. Weblate will automatically push all modifications to the evcc repository where they get reviewed and merged.
If you find a text that is not yet translatable in Weblate, you can help us by making it translatable. To do this, you can simply find the missing translation text in the code and apply similar changes as in these two Pull Requests:
Note: To ensure the build succeeds after creating new translations, make sure to include your new translations in both the de.json and en.json files.
We're always thankful for contributions. Docs, website and app have dedicated repositories. Please open a GitHub pull request in the respective repository.
- Documentation: evcc-io/docs
- Website: evcc-io/evcc.io
- iOS/Android App: evcc-io/app
By contributing to evcc, you agree that your contributions will be licensed under the existing license terms that apply to the respective parts of the project. This constitutes an implicit Contributor License Agreement (CLA), following GitHub's standard practice where contributions are made under the same terms as the project license.