Python Implementation of the ISO 15118 -2 1 and -20 2 protocols
The ISO 15118 -2 and -20 code live in the directory iso15118.
The primary dependencies to install the project are the following:
*If using a Windows machine, follow the same steps as below on a Linux VM.
There are two recommended ways of running the project:
Using Docker has the advantage of starting everything up automatically, including certificate generation, tests and linting, as well as spawning both the SECC and EVCC containers.
Building and running the docker file:
$ make build
$ make devNote that if Docker is used, the command make run will try to get the .env file.
The command make dev will fetch the contents of .env.dev.docker - thus,
in this case, the user does not need to create a .env file, as Docker will
automatically fetch the .env.dev.docker one.
The project includes a script to help on the generation of -2 and -20 certificates.
This script is located under iso15118/shared/pki/ directory and is called create_certs.sh.
The following command provides a guide for the script usage:
$ cd iso15118/shared/pki/
$ ./create_certs.sh -hUse the following commands to generate certificates for ISO 15118-2 and 15118-20:
$ ./create_certs.sh -v iso-2
$ ./create_certs.sh -v iso-20The JRE engine is only a requirement in Josev Community if using the Java-based EXI codec (EXIficient)4. Josev Professional uses our own Rust-based EXI codec.
Install the JRE engine with the following command:
sudo apt update && sudo apt install -y default-jreIn Ubuntu, the default version of Java installed by your distribution may not be recent enough. If so, you can manually install a more recent version of Java and configure it to be the default:
sudo apt install openjdk-17-jreDisplay the different installed versions of Java you have installed:
update-alternatives --query javaConfigure the more recent version to be the default:
update-alternatives --config javaThen follow the instructions to configure your desired version.
The project includes multiple environmental files, in the root directory, for different purposes:
.env.dev.docker- ENV file with development settings, tailored to be used with docker.env.dev.local- ENV file with development settings, tailored to be used with the local host
If the user runs the project locally, eg using $ make build && make run-secc,
it is required to create a .env file, containing the required settings.
To run for local development, simply copy the contents of .env.dev.local to .env.
Setting your local network interface
By default, .env.dev.local assumes the presence of an eth0 network interface.
If you are not using eth0 as your network interface, replace the NETWORK_INTERFACE value
in your local .env file with the one you are using.
The key-value pairs defined in the .env file directly affect the settings
present in secc_settings.py and evcc_settings.py. In these scripts, the
user will find all the settings that can be configured. For reference,
a table is included below.
We use Poetry to manage dependencies.
The recommended way to install Poetry is to use its installation script. See https://python-poetry.org/docs/#installation for instructions.
For convenience, the Makefile, present in the project, helps you to start up the controllers. Thus, in the terminal run:
$ make install-local
$ make poetry-shell
$ make run-seccThe above commands will do the following:
- Install all dependencies with Poetry
- Use the Poetry shell to activate the appropriate virtual environment
- Run the start script for SECC
$ poetry install
$ poetry shell
$ python iso15118/secc/start_secc.pyIf you wish to run the EVCC instead, use make run-evcc. Since the project includes
both the SECC and EVCC side, it is possible to test your application by starting both services.
Similar to the SECC, we can start the EVCC side as follows:
$ make install-local
$ make poetry-shell
$ make run-evccIt is possible to run up EVCC in different configurations. An example setting configuration for EVCC would be (15118-2, AC, EIM, TLS disabled mode), (15118-2/DINSPEC, DC, EIM/PnC, TLS enabled) etc. Examples for such configurations are provided under "iso15118/shared/examples/evcc/". The configuration could be passed in as a commandline argument as given below.
$ make run-evcc config=path_of_config_fileSupported settings in EVCC configuration are given below:
| Setting | Default Value | Description |
|---|---|---|
| supportedProtocols | DIN_SPEC_70121,ISO_15118_2,ISO_15118_20_AC,ISO_15118_20_DC |
Enabled communication protocols on EVCC. NOTE: ISO 15118 DC support is still under development |
| supportedEnergyServices | AC |
Selected energy services mode for EVCC. |
| useTls | True |
Whether or not the EVCC signals the preference to communicate with a TLS connection |
| enforceTls | False |
Whether or not the EVCC will only accept TLS connections |
| isCertInstallNeeded | False |
Indicates if the installation of a contract certificate is needed |
| energyTransferMode | AC_three_phase_core |
Energy transfer mode requested for the current charging session. |
| sdpRetryCycles | 1 |
Indicates how often shall SDP (SECC Discovery Protocol) retries happen before reverting to using nominal duty cycle PWM-based charging |
| maxContractCerts | 3 |
Maximum amount of contract certificates the EV stores. |
| maxSupportingPoints | 1024 |
Indicates the maximum number of entries the EVCC supports within the sub-elements of a ScheduleTuple |
The SECC and EVCC have been tested together under:
- Linux - Ubuntu and Debian distros
- MacOS
For the system to work locally, the network interface needs to have an IPv6 link-local address assigned.
For Docker, the docker-compose.yml was configured to create an IPv6 network
called ipv6_net, which enables the containers to acquire a link-local address - this is required to establish an
ISO 15118 communication. This configuration is fine if the user wants to test, in isolation, the EVCC and SECC, and
allow ISO 15118 communication. This configuration works for both Linux and BSD systems.
However, the usage of an internal ipv6_net network, in Docker, does not allow the
host to reach link-local addresses. This would pose a problem, as it would require
the application to use the global link address, which is not supported by ISO 15118.
The solution is to use the network_mode: host feature of Docker, which replicates
the host network topology within the Docker world, ie the containers and the
host share the same network. This way, Docker can directly access the virtual
network interface created by the HomePlug Green PHY module, making it possible
to use the link-local address.
Currently, network_mode: host just works within Linux environments 5 6.
Since the Switch team relies mostly on MacOS and this project is on a development stage,
network_mode is not used by default; it is possible to use it, however, if the contents of the
file docker-compose-host-mode.yml are copied to the main compose file, docker-compose.yml.
In that case, we advise you to back up the compose file.
The default configuration values can be modified by setting them as environment variables. The following table provides a few of the available variables:
| ENV | Default Value | Description |
|---|---|---|
| NETWORK_INTERFACE | eth0 |
HomePlug Green PHY Network Interface from which the high-level communication (HLC) will be established |
| SECC_ENFORCE_TLS | False |
Whether or not the SECC will enforce a TLS connection |
| PKI_PATH | <CWD>/iso15118/shared/pki/ |
Path for the location of the PKI where the certificates are located. By default, the system will look for the PKI directory under the current working directory |
| LOG_LEVEL | INFO |
Level of the Python log service |
| MESSAGE_LOG_JSON | True |
Whether or not to log the EXI JSON messages (only works if log level is set to DEBUG) |
| MESSAGE_LOG_EXI | False |
Whether or not to log the EXI Bytestream messages (only works if log level is set to DEBUG) |
| PROTOCOLS | DIN_SPEC_70121,ISO_15118_2,ISO_15118_20_AC,ISO_15118_20_DC |
Enabled communication protocols on SECC. |
| AUTH_MODES | EIM,PNC |
Selected authentication modes for SECC |
| USE_CPO_BACKEND | False |
Indicates if backend integration is available to fetch certificates |
| ENABLE_TLS_1_3 | False |
Enables TLS 1.3 for SECC-EVCC communication. |
Copyright [2022] [Switch]
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.