Remote - Set Up
1. Post Remote CallBack #
Callback Request
Before being able to send a remote action, you have to configure the HTTP callback that will be sent to your webhook.
This callback specifies your webhook config, a retry policy and a batch notification policy. You can set up several callbacks. You will then execute a remote action using the callback the most appropriate for the situation.
Here is an overview of an HTTP request intended to create a remote callback.
1
2
3
4
5
6
7
8
9
$ curl \
--POST \
--url 'https://api-cert.groupe-psa.com/connectedcar/{version}/fleets/{fid}/remote/callbacks' \
--data 'client_id=<client_id>' \
--header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
--cert 'path/to/client_cert.pem[:<cert_password>]' \
--key 'path/to/key.pem' \
--cacert 'path/to/ca_cert.pem' \
--data '<check out HTTP body>' \
1
2
3
4
5
6
7
{
"retryPolicy": { },
"batchNotify": { },
"callback": { },
"label": "callback-name",
"extendedEventParam": [ ]
}
Below is a description of the JSON models explaining how to configure a callback. Please refer to API Reference models to read a full description of the callback configuration.
- RemoteCallbackSubscribe: this JSON object allow you to configure your remote callback:
- retryPolicy: this where you set retry policy, it’s in case your webhook has not received the callback, whatever is the reason.
- batchNotify: you can set this object in case you need to receive notification in batch instead of one by one.
- callback>webhook: this required object is where you will set the address and name of your webhook. This is also where you can customize the HTTP notification (example: for authentication purpose).
- notificationTypes: this array of remotes allow you to subscribe this callback to one or more actions.
Example
This request ask to create a callback named “my-post-callback” with the following parameters:
- If the callback notification is not received, the request will be sent again every 120s until it’s properly delivered.
- The callback will be sent once 10 callback notifications are ready to be sent or 300s after triggering.
- The callback will be sent to your
https://my.post.callback
webhook with the vin of the vehicle as a query path param and yourBasic authentication
in HTTP header. - This callback can be used in order to send remote actions:
ThermalPreconditioning
&ElectricBatteryChargingRequest
.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"retryPolicy": {
"policy": "Always",
"maxRetryNumber": 3,
"retryDelay": 120
},
"batchNotify": {
"size": 10,
"timeWindow": 300
},
"callback": {
"webhook": {
"target": "https://my.post.callback",
"name": "My_Webhook",
"attributres": [
{
"type":"Header",
"key":"Authorization",
"value":"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
}
]
}
},
"label": "my-post-callback",
"notificationTypes": [
"ThermalPreconditioning",
"ElectricBatteryChargingRequest"
]
}
Callback Response
Here is an example of HTTP response after POSTING a new remote callback.
1
2
3
4
5
{
"_links": {...},
"callbackId": "c7eeaafdf0ab9683d5a1b8d51572014996540m0021",
"status": "Running"
}
The callback have been created with id=c7eeaafdf0ab9683d5a1b8d51572014996540m0021
. This callbackId will be sent with every notification to your webhook.
Important: You will need this ID to POST a remote action to a vehicle with this callback.
2. Post Remote Action #
Remote Request
Once you have a dedicated callback, you are able to POST a remote action to a vehicle. Choose a vehicle id (you can retrieve it with the API status), then send this kind of request:
1
2
3
4
5
6
7
8
9
$ curl \
--POST \
--url 'https://api-cert.groupe-psa.com/connectedcar/{version}/fleets/{fid}/vehicles/{vid}/callbacks/{cbid}/remotes' \
--data 'client_id=<client_id>' \
--header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
--cert 'path/to/client_cert.pem[:<cert_password>]' \
--key 'path/to/key.pem' \
--cacert 'path/to/ca_cert.pem' \
--data '<check out HTTP body>' \
1
2
3
4
5
6
{
"label": "remote_name",
"door": {
"state": "Unlocked"
}
}
In this API you have to replace this fields:
- {fid} is the id of your fleet.
- {vid} is the id of the vehicle to which you want to send the remote action.
- {cbid} is the id of one of your callbacks (see 1. Post remote Callback).
You can browse the Remote Object in the reference section to have more info about how to send a specific remote action:
Remote Actions
Object Name | Description | Example |
---|---|---|
RemotePreconditioning | Choose between immediate preconditionning or not, and set a program with recurrence or not, start time, occurence during the week then, choose to enable or not this program. Note: Using the key/value Slot you can register up to 4 PreconditionPrograms. |
{ "label": "string", "preonditionning": { "airConditioning": { "immediate": false, "programs": [ { "recurrence": "Daily", "start": "PT14H30M", "occurence": { "day": [ "Mon" ] }, "slot": 0, "enabled": true } ] } } } |
RemoteSetImmobilization | Set to activate to true if you need to immobilize a vehicle. You can use this feature in addition to “RemoteSetStolen”. |
{ "immobilization": { "activate": true } } |
RemoteDoorsState | Set state to Locked or Unlocked . |
{ "door": { "state": "Unlocked" } } |
RemoteHorn | Honk the vehicel horn. | { "horn": { "state": "Activated" } } |
RemoteCharging | You can choose between immediate recharge or nextDelayedTime with a timestamp RFC3339 before the charge activation. To stop a charge use set immediate to false . |
{ "charging": { "nextDelayedTime": "string", "immediate": false } } Stop: { "charging": {"immediate": false} } |
RemoteSetStolen | Set stolen to true if you want the vehicle to be in stolen state. It’s mean that it will stay awake and refresh lastPosition on a regular basis. |
{ "stolen": { "stolen": true } } |
RemoteLights | Set a light blinking. | { "ligths": { "on": true } } |
RemoteState | Set action: state to retrieve an updated status of the vehicle. |
{ "state": { "action": "state" } } |
RemoteNavigation | Set action: navigation to send a remote navigation on the guidance system of the vehicle. You can choose to send a notification to the driver through the HMI, before launching the navigation with "driverApproval": true . The field "positions": [...] is an array of GeoJSON points where the last point is the final destination and the other points are waypoints, maximum 10 points. |
{"navigation": { "driverApproval": true, "positions": [ { "type": "Point", "coordinates": [ 5.970338, -62.536239 ] } ]}} |
Be careful: you can send only one Remote Action at once. If you need to send several Remote Actions you have to send several HTTP POST requests to /fleets/{fid}/vehicles/{vid}/callbacks/{cbid}/remotes. However, you can use the same callback for those Remote Action.
Remote Response
This is an example of HTTP response when you POST remote action:
1
2
3
4
5
6
7
{
"_links": { ... },
"remoteActionId": "909bkqacjb3bfhdhjanahbc244jj2lixfbe2e52u5y",
"type": [
"ThermalPreconditioning"
]
}
RemoteActionID is the unique identifier of the remote. This id will be sent to your callback with your remote action reports.