Merge pull request #239 from camueller/automate-doc

Automate documentation / Supported vehicles list

Author: meatpiHQ

.vehicle_profiles/merge.js

@@ -28,7 +28,24 @@ result.cars.sort((a,b) => {
     return (first < second) ? -1 : (first > second ) ? 1 : 0;
 });
 
-result = JSON.stringify(result);
+const resultString = JSON.stringify(result);
 //Use below line instead for generating pretty json
 // result = JSON.stringify(result, null, 2);
-await writeFile(target, result)
+await writeFile(target, resultString)
+
+const models = result.cars.map(car => car.car_model).filter(model => model !== 'AAA: Generic');
+let supportedVehiclesListContent = '';
+supportedVehiclesListContent += '<!--\n';
+supportedVehiclesListContent += '================================================================\n'
+supportedVehiclesListContent += 'THIS FILE WAS GENERATED! DO NOT UPDATE OR YOUR CHANGES ARE LOST!\n'
+supportedVehiclesListContent += '================================================================\n'
+supportedVehiclesListContent += '-->\n';
+supportedVehiclesListContent += '# Supported Vehicles\n';
+supportedVehiclesListContent += 'For vehicles listed below a WiCAN vehicle profiles exists:\n';
+models.forEach(model => supportedVehiclesListContent += `- ${model}\n`);
+
+const supportedVehiclesListFilepath = await glob('../docs/content/*.Config/*.Automate/*.Supported_Vehicles.md')
+if(supportedVehiclesListFilepath.length == 0 || supportedVehiclesListFilepath.length != 1) {
+    throw new Error('Unable to determine automateDirectory');
+}
+await writeFile(supportedVehiclesListFilepath[0], supportedVehiclesListContent);

docs/content/0.Config/6.Automate/1.Usage.md

@@ -0,0 +1,55 @@
+---
+title: Usage
+---
+
+# Automate
+
+The "Automate" feature can be used to **periodically request one or more PID**s.
+
+First of all **the `Protocol` in the `CAN` section on the "Settings" tab has to be set to `AutoPID`**
+
+Configuration of "Automate" itself is done on the "Automate" tab.
+
+Responses can be monitored:
+- by monitoring the MQTT subject configured if [MQTT is enabled](../MQTT.md)
+  ![image](/config/automate/monitor_mqtt.png)
+  
+- pointing the Web browser to `http://<WiCAN IP adress>/autopid_data` if [MQTT is NOT enabled](../MQTT.md)
+  ![image](/config/automate/monitor_http.png)
+
+## Vehicle Profiles
+Initially the download of **vehicle profiles** has to be triggered by pressing the sync button next to the `Vehicle Model` dropdown box. These vehicle profiles are car vendor and/or model specific and contain some popular PIDs (e.g. SoC, SoH). There is a growing [list of supported vehicles](2.Supported_Vehicles.md).
+
+If WiCAN cannot download vehicles profiles for any reason you man also [download in manually](https://github.com/meatpiHQ/wican-fw/blob/main/vehicle_profiles.json) and press the `Choose File` button to select the file downloaded.
+
+In order to use vehicle profiles `Vehicle Specific` has to be set to `Enable`.
+
+If vehicles profiles are available to WiCAN the appropriate `Vehicle Model` should be selected from the drop-down box. Use the reload button next to it to trigger the download of the most up-to-date vehicle profiles.
+
+In `Cycle Time(ms)` the interval is configured after which the PIDs, contained in the vehicle profile, are requested. 
+
+The results are posted to the MQTT topic specified in `Destination Topic` if [MQTT is enabled](../MQTT.md). 
+
+![image](/config/automate/automate.png)
+
+
+## Custom PIDs
+
+If there is no vehicle profile for your car, or it does not contain the PIDs you would like to use, the "Custom PIDs" feature should be used. Basically the same parameters as contained in the vehicle profiles can be entered:
+
+- **Custom Initialisation**: will be sent by WiCAN prior requesting particular PIDs
+- **Name**: the attribute name containing the result of the PID request
+- **Init**: will be sent by WiCAN prior requesting this particular PID
+- **Expression**: is used to calculate the attribute value from the bytes returned for this PID
+- **Period**: the interval after which this PID is requested again
+- **Type**: currently only `MQTT_Topic` can be selected
+- **Send_to**: the MQTT topic the result should be sent to
+
+In order to add more PIDs the `New` button can be used.
+The `Delete` button deletes the configuration of the corresponding PID 
+
+In order to use Custom PIDs `Vehicle Specific` has to be set to `Disable`.
+
+**At the moment Custom PIDs are only supported over MQTT**. Therefore [MQTT has to be enabled](../MQTT.md).
+
+![image](/config/automate/custom_pids.png)

docs/content/0.Config/6.Automate/2.Supported_Vehicles.md

@@ -0,0 +1,19 @@
+<!--
+================================================================
+THIS FILE WAS GENERATED! DO NOT UPDATE OR YOUR CHANGES ARE LOST!
+================================================================
+-->
+# Supported Vehicles
+For vehicles listed below a WiCAN vehicle profiles exists:
+- BMW: i3
+- BYD: Atto 3
+- Hyundai: Ioniq2017
+- Hyundai: Ioniq5/Ioniq6/Kona
+- Jaguar: I-PACE
+- Kia: Niro PHEV
+- Nissan : leaf-ze1
+- Renault: Kangoo Z.E
+- Toyota: Rav4
+- VW: e-Golf
+- VW: e-Up
+- VW: id-3

docs/content/0.Config/6.Automate/_dir.yml

@@ -0,0 +1,2 @@
+title: Automate
+icon: material-symbols:automation