How to document a vehicle

[epenet]

General guidelines for documenting a vehicle

Install the CLI

First, please make sure that you have installed the CLI version of renault-api.
This can be done with pip or equivalent.

foo@bar:~$ pip install renault-api[cli]

Authenticate and initial installation checks

Prepare your MyRenault credentials, then run the login command to store your credentials locally.
Running the status command will then confirm that the installation was OK.

foo@bar:~$ renault-api login
foo@bar:~$ renault-api status

Test simple data endpoints

Now you need to check manually the endpoints using the CLI.
Please note that the {account_id} and {vin} will be automatically converted, so there is no need to manually adjust them before running the command.

You can start by checking the default endpoints. The default endpoints are listed in _DEFAULT_ENDPOINTS of https://github.com/hacf-fr/renault-api/blob/main/src/renault_api/kamereon/models.py

Let's start with the default "read" endpoints (please note that the prefix /commerce/v1/accounts/{account_id}/kamereon is always the same):

foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/vehicles/{vin}/alerts
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v2/cars/{vin}/battery-status
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/charge-history
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/charge-mode
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/charge-schedule
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/charging-settings
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/cockpit
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/hvac-history
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/hvac-sessions
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/hvac-settings
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/hvac-status
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/location
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/lock-status
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/notification-settings
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/pressure
foo@bar:~$ renault-api http get /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/res-state

If some of these do not work, you can test the _KCM_ENDPOINTS

Test action endpoints

The action endpoints are trickier to test, as they need a valid payload.

The payload needs to have surrounding double-quotes, and inner quotes need to be single-escaped (on Linux) or double-escaped (on Windows)

A sample payload for "start charge" action would look like this:
"{\"data\": {\"type\": \"ChargingStart\", \"attributes\": {\"action\": \"start\"}}}"
or
"{\\"data\\": {\\"type\\": \\"ChargingStart\\", \\"attributes\\": {\\"action\\": \\"start\\"}}}"

Charge start

foo@bar:~$ renault-api --log http post /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/actions/charging-start "{\"data\": {\"type\": \"ChargingStart\", \"attributes\": {\"action\": \"start\"}}}"

Lights

foo@bar:~$ renault-api --log http post /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/actions/horn-lights "{\"data\": {\"type\": \"HornLights\", \"attributes\": {\"action\": \"start\", \"target\": \"lights\"}}}"

Horn

foo@bar:~$ renault-api --log http post /commerce/v1/accounts/{account_id}/kamereon/kca/car-adapter/v1/cars/{vin}/actions/horn-lights "{\"data\": {\"type\": \"HornLights\", \"attributes\": {\"action\": \"start\", \"target\": \"horn\"}}}"

[epenet]

Troubleshooting:

ModuleNotFoundError: No module named 'click'

click is only installed when you install renault-api with [cli] option. Please make sure the the correct installation command is used:

foo@bar:~$ pip install renault-api[cli]

[epenet]

Create PR and update Home Assistant:

Create a PR with your model updates

After investigating the capabilities of your model, you need to create a PR to update the _VEHICLE_ENDPOINTS for your model code in /src/renault_api/kamereon/models.py.
You can use previous PRs as example #1763 / #1787 / #1785

renault-api/src/renault_api/kamereon/models.py

Lines 153 to 158 in 7135284

	_VEHICLE_ENDPOINTS: dict[str, dict[str, EndpointDefinition | None]] = {
	"A5E1AE": { # Alpine A290
	"actions/charge-start": None, # Reason: The access is forbidden,
	"actions/charge-stop": None, # Reason: The access is forbidden,
	"actions/horn-start": _DEFAULT_ENDPOINTS["actions/horn-start"],
	"actions/hvac-start": _DEFAULT_ENDPOINTS["actions/hvac-start"],

Create a PR to build a release

Once the model PR above has been created, accepted and merged, a release needs to be built before Home Assistant can be updated. This is done by creating a PR to update the version number in /pyproject.toml. You can use previous PR #1856 as guidance.

renault-api/pyproject.toml

Line 3 in 7135284

version = "0.5.2"

Create a Home Assistant PR to use the new release

Once the new release is available, a PR needs to be made inside Home Assistant to use the new version. Three files need to be updated:

• /homeassistant/components/renault/manifest.json
• /requirements_all.txt
• /requirements_test_all.txt

You can use previous PR home-assistant/core#159448 as guidance.