diff --git a/README.md b/README.md index b5d1380..1b4231f 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,12 @@ [www.meatpi.com](https://www.meatpi.com) --- -## MeatPi [Discord server](https://discord.com/invite/2hpHVDmyfw) -## Please update to the [latest firmware version](https://github.com/meatpiHQ/wican-fw/releases/) +# [Documentation](https://meatpihq.github.io/wican-fw/) | [Firmware updates](https://github.com/meatpiHQ/wican-fw/releases/) | [Discord server](https://discord.com/invite/2hpHVDmyfw) + --- -# [Official Docs](https://meatpihq.github.io/wican-fw/) -We are currently in the process of migrating from this large README.md into the proper docs. ## Order on [**Mouser**](https://www.mouser.com/c/?m=MeatPi) or [**Crowd Supply!**](https://www.crowdsupply.com/meatpi-electronics) -

- ---- # WiCAN PRO ### Ongoing crowdfunding campaign for a new product in development! If you would like to support this project, please subscribe for updates on [**Crowd Supply!**](https://www.crowdsupply.com/meatpi-electronics/wican-pro) @@ -46,15 +41,6 @@ We are currently in the process of migrating from this large README.md into the - [API](#api) - [Build](#build) - [Description](#description) -- [Configuration](#configuration) - - [WiFi/CAN Configuration](#1-wifican-configuration) - - [BUSMaster](#2-busmaster) - - [Realdash](#3-realdash) - - [SavvyCAN](#4-savvycan) - - [webCAN](http://webcan.meatpi.com) -- [SocketCAN](#socketcan) - - [WiFi](#1-wifi) - - [USB](#2-usb) - [ELM327 OBD2 Protocol](#elm327-obd2-protocol) - [Firmware Update](https://meatpihq.github.io/wican-fw/config/firmware-update) - [OTA](https://meatpihq.github.io/wican-fw/config/firmware-update) @@ -113,137 +99,6 @@ WiCAN-USB can also be used as a USB-to-CAN adapter when Wi-Fi connectivity is no ![Modes](https://user-images.githubusercontent.com/94690098/222961571-bd137341-808a-4f0a-9528-789fe24d640e.png "Connection Mode") -# Configuration: --------- - -## 1. WiFi/CAN Configuration: -1. Power up the device using the USB cable, or by plugging into the OBD-II connector. -2. The blue LED will light ON, and a WiFi device access point will start. The SSID will look like: WiCAN_xxxxxxxxxxxx -3. Connect to the SSID using the default password: @meatpi# -4. Using a web browser, go to http://192.168.80.1/ -5. The status menu shows the device current configuration, if in Ap+Station mode it will show the device IP on your local network if connected successfully. -6. The WiFi menu lets you configure the WiFi parameters. It is recommended that you change the AP access point. -7. The CAN menu allows to choose the protocol set the bitrate and TCP/UPD port number. -8. When ready click submit Changes button and the device will store the configuration reboot immediately. - -**Note: If you intend to use the device in AP mode it is recommand that you disable the BLE function** - -![Configuration page](https://github.com/meatpiHQ/WiCAN/blob/main/images/settings40.png?raw=true "Config page") - -## 2. BUSMaster -You need to download the right version of BUSMaster provided in this [**Link**](https://drive.google.com/drive/folders/1qJelUAHGrn_YbNIP0Jk_KmNENG-hKbtl?usp=sharing). Here is how to setup the hardware. - -### **Device Configuration:** - -1. Go to configuration webpage. -2. Baudrate can be set in BUSMaster configuration -3. Set "Port Type" = TCP -4. Set "Protocol" = slcan -5. Click submit changes. - -### **BUSMaster Configuration:** - -1. Select VSCom CAN-API by clicking on 'Driver Selection -> VSCom CAN-API" -2. Then Click on 'Channel Configuration -> Advanced' -3. Fill in the IP and port. **Example: 192.168.80.1:3333** -4. Check the 'Hardware Timestamps' check box. -5. Choose the Baudrate. -6. Click 'OK', then Click the Connect button on the top left corner. - - - - -## 3. RealDash -WiCAN-OBD and WiCAN-USB can connect with RealDash using either WiFi or BLE. **The protocol and CAN bitrate must be set using the configuration page**. BLE is supported only on Android and iOS. Windows 10 supports only WiFi connections. Additionally, _WiCAN-USB can connect using the USB interface_. - -### USB Device Configuration (WiCAN-USB only): -1. Go to garage then click on the dashboard. -2. Click Add connection. -3. Select Adapter (CAN/LIN) -4. Select RealDash CAN -5. Select SERIAL/USB -6. Select device -7. Set Baud RATE: 4000000 (This is the usb/serial buadrate not the CAN bitrate) -8. Click next then Done - -### WiFi Device Configuration: - -1. Go to configuration webpage. -2. Select the baudrate -3. Set "Port Type" = TCP -4. Set "Protocol" = reladash 66 -5. Click submit changes. - -### RealDash Configuration: -1. Go to garage then click on the dashboard. -2. Click Add connection. -3. Select Adapter (CAN/LIN) -4. Select RealDash CAN -5. Select WIFI/LAN -6. Enter IP and Port -7. Click Done - -### BLE Device Configuration: - -**If you're using firmware verion v1.64 or below please update to the [latest version](https://github.com/meatpiHQ/wican-fw/releases/) before enabling BLE** - -1. Go to configuration webpage. -2. Select the baudrate -3. Set the "BLE Status" to enable - -**Note: When the BLE is connected, the device will automatically turn off the WiFi configuration access point. Once BLE is disconnected the configuration access point will turn back on.** - -## 4. SavvyCAN - -1. Download [SavvyCAN](https://www.savvycan.com/) -2. Connect to the device AP. -3. Open SavvyCAN and Click Connection->Open Connection Window->Add New Device -4. Select "Network Connection", if you're on the same network it auto detect the IP. -5. Click Create New Connection. -6. Then select "Enable Bus" checkbox. - -# SocketCAN - -## 1. WIFi: - -Change to protocol in the device configuration page to "slcan", then create a virtual serial port over TCP on your Linux machine. If WiCAN is connected to your home network replace "192.168.80.1" with device IP. - -``` -sudo socat pty,link=/dev/netcan0,raw tcp:192.168.80.1:3333 & -sudo slcand -o -c -s8 /dev/netcan0 can0 -sudo ifconfig can0 txqueuelen 1000 -sudo ifconfig can0 up -``` - -## 2. USB - -``` -sudo slcand -o -s6 -t sw -S 4000000 /dev/ttyACM0 can0 -sudo ifconfig can0 txqueuelen 1000 -sudo ifconfig can0 up -``` -# ELM327 OBD2 Protocol - -**If you're using firmware verion v1.64 or below please update to the [latest version](https://github.com/meatpiHQ/wican-fw/releases/) before enabling BLE** - -1. Go to configuration webpage. -2. Select the baudrate -3. Set "Port Type" = TCP -4. Set "Protocol" = elm327 -5. Enable BLE if needed. [Note](https://github.com/meatpiHQ/wican-fw#important-notes) -6. Click submit changes. - -### OBD2 in RealDash - -1. Go to garage then click on the dashboard. -2. Click Add connection. -3. Select Adapter ``` OBD2 ``` -4. Select Bluetooth or WiFi -5. If WiFi fill in the IP 192.168.80.1 and port 3333. -6. Click on ``` OBD2 PROTOCOL ``` and select your car protocol, (11 bit ID, 500Kbit) or (11 bit ID, 250Kbit) -7. Activate ``` Request Only First Reply ``` -8. Click Done. - --- -© 2023 meatPi Electronics | www.meatpi.com | PO Box 5005 Clayton, VIC 3168, Australia +© 2024 meatPi Electronics | www.meatpi.com | PO Box 5005 Clayton, VIC 3168, Australia diff --git a/docs/content/0.Config/1.WiFi.md b/docs/content/0.Config/1.WiFi.md index e22883a..7bb846c 100644 --- a/docs/content/0.Config/1.WiFi.md +++ b/docs/content/0.Config/1.WiFi.md @@ -1,7 +1,7 @@ # Configuring WiFi ## Access point mode -By default your WiCAN will act as Access Point and create its own WiFi network named `WiCAN_xxxxxxx`. You can connect to it with the default password `@meatpi#`. +By default your WiCAN will act as Access Point and create its own WiFi network named **`WiCAN_xxxxxxx` where `xxxxxxx` is the device ID of the WiCAN** you are using. You can connect to it with the default password `@meatpi#`. If you are using a phone, you may need to wait a few seconds and confirm you want to connect to a network that does not provide internet. @@ -11,6 +11,8 @@ Once connected you can open `http://192.168.80.1` in your browser to access the It is probably a good idea to change the Access point password in the user interface on the "Settings" tab. Otherwise anyone can connect to your WiCAN if he can get close to your car while the WiCAN is powered on. +**Note: If you intend to use the device in AP mode it is recommand that you disable the BLE function** + ## Connect WiCAN to your home WiFi network In the user interface of the WiCAN go to the `Settings` tab to change `Mode` to `AP+Station`, and input the `SSID` and `Password` of your home WiFi network and press the `Submit changes` button. diff --git a/docs/content/0.Config/2.CAN.md b/docs/content/0.Config/2.CAN.md new file mode 100644 index 0000000..c74a798 --- /dev/null +++ b/docs/content/0.Config/2.CAN.md @@ -0,0 +1,16 @@ +# CAN + +On the "Settings" tab CAN access has to be configured: + +![image](/config/can.png) + +## ELM327 OBD2 Protocol + +**If you're using firmware verion v1.64 or below please [update to the latest version](4.Firmware-Update.md) before enabling BLE** + +1. Go to configuration webpage. +2. Select the baudrate +3. Set "Port Type" = TCP +4. Set "Protocol" = elm327 +5. Enable BLE if needed. [Note](https://github.com/meatpiHQ/wican-fw#important-notes) +6. Click submit changes. diff --git a/docs/content/0.Config/3.MQTT.md b/docs/content/0.Config/3.MQTT.md new file mode 100644 index 0000000..6995d2e --- /dev/null +++ b/docs/content/0.Config/3.MQTT.md @@ -0,0 +1,13 @@ +# MQTT + +Currently only non-secure MQTT is supported, it's highly recommended that you only use it with local MQTT broker and not use public brokers otherwise your CAN bus might be publicly exposed. + +To use the MQTT client it has to be enabled on the "Settings" tab: + +![image](/config/mqtt_enable.png) + +Of couse the broker, topics and logging have to be configured as well: + +![image](/config/mqtt.png) + +The [WiCAN device ID](../0.Config/1.WiFi.md) is part of the topics in order to be able to communicate with multiple WiCAN devices if needed. diff --git a/docs/content/0.Config/3.Firmware-Update.md b/docs/content/0.Config/4.Firmware-Update.md similarity index 100% rename from docs/content/0.Config/3.Firmware-Update.md rename to docs/content/0.Config/4.Firmware-Update.md diff --git a/docs/content/0.Config/Automate.md b/docs/content/0.Config/Automate.md new file mode 100644 index 0000000..9acdb7f --- /dev/null +++ b/docs/content/0.Config/Automate.md @@ -0,0 +1,3 @@ +# Automate + +Not yet documented ... \ No newline at end of file diff --git a/docs/content/1.home assistant/_dir.yml b/docs/content/1.Home Assistant/_dir.yml similarity index 100% rename from docs/content/1.home assistant/_dir.yml rename to docs/content/1.Home Assistant/_dir.yml diff --git a/docs/content/1.home assistant/index.md b/docs/content/1.Home Assistant/index.md similarity index 56% rename from docs/content/1.home assistant/index.md rename to docs/content/1.Home Assistant/index.md index d1d21e3..5ba6328 100644 --- a/docs/content/1.home assistant/index.md +++ b/docs/content/1.Home Assistant/index.md @@ -5,7 +5,7 @@ description: Overview of Home Assistant Integration with WiCAN ## Home Assistant -WiCAN integrates seamlessly with Home Assistant using the official integration, which communicates via HTTP, eliminating the need for MQTT. We recommend using the official integration for the best experience. +WiCAN integrates seamlessly with [Home Assistant](https://www.home-assistant.io/) using the official integration, which communicates via HTTP, eliminating the need for MQTT. We recommend using the official integration for the best experience. Alternatively, WiCAN can still connect to Home Assistant via MQTT. For setup instructions, refer to the [MQTT guide](/home-assistant/mqtt/). diff --git a/docs/content/1.home assistant/integration_setup.md b/docs/content/1.Home Assistant/integration_setup.md similarity index 100% rename from docs/content/1.home assistant/integration_setup.md rename to docs/content/1.Home Assistant/integration_setup.md diff --git a/docs/content/1.home assistant/mqtt.md b/docs/content/1.Home Assistant/mqtt.md similarity index 100% rename from docs/content/1.home assistant/mqtt.md rename to docs/content/1.Home Assistant/mqtt.md diff --git a/docs/content/2.Automate/_dir.yml b/docs/content/2.Automate/_dir.yml deleted file mode 100644 index 11d3ced..0000000 --- a/docs/content/2.Automate/_dir.yml +++ /dev/null @@ -1,2 +0,0 @@ -title: Automate -icon: simple-icons:settings-heart diff --git a/docs/content/2.Car_Scanner/Usage.md b/docs/content/2.Car_Scanner/Usage.md new file mode 100644 index 0000000..b6facbc --- /dev/null +++ b/docs/content/2.Car_Scanner/Usage.md @@ -0,0 +1,3 @@ +# Car Scanner + +Not yet documented ... \ No newline at end of file diff --git a/docs/content/2.Car_Scanner/_dir.yml b/docs/content/2.Car_Scanner/_dir.yml new file mode 100644 index 0000000..e63938b --- /dev/null +++ b/docs/content/2.Car_Scanner/_dir.yml @@ -0,0 +1,2 @@ +title: Car Scanner +icon: material-symbols:car-rental diff --git a/docs/content/3.BUSMASTER/Usage.md b/docs/content/3.BUSMASTER/Usage.md new file mode 100644 index 0000000..36dd55c --- /dev/null +++ b/docs/content/3.BUSMASTER/Usage.md @@ -0,0 +1,24 @@ +## BUSMASTER +[BUSMASTER](https://rbei-etas.github.io/busmaster/) is an Open Source Software tool to Simulate, Analyze and Test data bus systems such as CAN, LIN. +You need to download the right version of BUSMaster provided in this [**Link**](https://drive.google.com/drive/folders/1qJelUAHGrn_YbNIP0Jk_KmNENG-hKbtl?usp=sharing). + +Here is how to set up the hardware: + +### **Device Configuration:** + +1. Go to configuration webpage. +1. Baudrate can be set in BUSMaster configuration +1. Set "Port Type" = TCP +1. Set "Protocol" = slcan +1. Click submit changes. + +### **BUSMaster Configuration:** + +1. Select VSCom CAN-API by clicking on 'Driver Selection -> VSCom CAN-API" +1. Then Click on 'Channel Configuration -> Advanced' +1. Fill in the IP and port. **Example: 192.168.80.1:3333** +1. Check the 'Hardware Timestamps' check box. +1. Choose the Baudrate. +1. Click 'OK', then Click the Connect button on the top left corner. + +![image](/busmaster/vscan_api_device_config.png) diff --git a/docs/content/3.BUSMASTER/_dir.yml b/docs/content/3.BUSMASTER/_dir.yml new file mode 100644 index 0000000..2ed60c8 --- /dev/null +++ b/docs/content/3.BUSMASTER/_dir.yml @@ -0,0 +1,2 @@ +title: BUSMASTER +icon: material-symbols:partner-exchange diff --git a/docs/content/4.RealDash/Usage.md b/docs/content/4.RealDash/Usage.md new file mode 100644 index 0000000..f0f65d3 --- /dev/null +++ b/docs/content/4.RealDash/Usage.md @@ -0,0 +1,52 @@ +## RealDash +WiCAN-OBD and WiCAN-USB can connect with [RealDash](https://realdash.net) using either WiFi or BLE. BLE is supported only on Android and iOS. Windows 10 supports only WiFi connections. Additionally, _WiCAN-USB can connect using the USB interface_. + +**The protocol and CAN bitrate must be set using the configuration page** + +### USB Device Configuration (WiCAN-USB only): +1. Go to garage then click on the dashboard. +1. Click Add connection. +1. Select Adapter (CAN/LIN) +1. Select RealDash CAN +1. Select SERIAL/USB +1. Select device +1. Set Baud RATE: 4000000 (This is the usb/serial buadrate not the CAN bitrate) +1. Click next then Done + +### WiFi Device Configuration: + +1. Go to configuration webpage. +1. Select the baudrate +1. Set "Port Type" = TCP +1. Set "Protocol" = reladash 66 +1. Click submit changes. + +### RealDash Configuration: +1. Go to garage then click on the dashboard. +1. Click Add connection. +1. Select Adapter (CAN/LIN) +1. Select RealDash CAN +1. Select WIFI/LAN +1. Enter IP and Port +1. Click Done + +### BLE Device Configuration: + +**If you're using firmware verion v1.64 or below please update to the [latest version](https://github.com/meatpiHQ/wican-fw/releases/) before enabling BLE** + +1. Go to configuration webpage. +1. Select the baudrate +1. Set the "BLE Status" to enable + +**Note: When the BLE is connected, the device will automatically turn off the WiFi configuration access point. Once BLE is disconnected the configuration access point will turn back on.** + +### OBD2 + +1. Go to garage then click on the dashboard. +1. Click Add connection. +1. Select Adapter ``` OBD2 ``` +1. Select Bluetooth or WiFi +1. If WiFi fill in the IP 192.168.80.1 and port 3333. +1. Click on ``` OBD2 PROTOCOL ``` and select your car protocol, (11 bit ID, 500Kbit) or (11 bit ID, 250Kbit) +1. Activate ``` Request Only First Reply ``` +1. Click Done. diff --git a/docs/content/4.RealDash/_dir.yml b/docs/content/4.RealDash/_dir.yml new file mode 100644 index 0000000..e4eddb0 --- /dev/null +++ b/docs/content/4.RealDash/_dir.yml @@ -0,0 +1,2 @@ +title: RealDash +icon: material-symbols:electric-meter diff --git a/docs/content/5.SavvyCAN/Usage.md b/docs/content/5.SavvyCAN/Usage.md new file mode 100644 index 0000000..17d2889 --- /dev/null +++ b/docs/content/5.SavvyCAN/Usage.md @@ -0,0 +1,8 @@ +## SavvyCAN +[SavvyCAN](https://www.savvycan.com/) is a cross platform CAN bus reverse engineering and capture tool. +1. Download [SavvyCAN](https://www.savvycan.com/) +1. Connect to the device AP. +1. Open SavvyCAN and Click Connection->Open Connection Window->Add New Device +1. Select "Network Connection", if you're on the same network it auto detect the IP. +1. Click Create New Connection. +1. Then select "Enable Bus" checkbox. diff --git a/docs/content/5.SavvyCAN/_dir.yml b/docs/content/5.SavvyCAN/_dir.yml new file mode 100644 index 0000000..021210d --- /dev/null +++ b/docs/content/5.SavvyCAN/_dir.yml @@ -0,0 +1,2 @@ +title: SavvyCAN +icon: material-symbols:camera-rounded diff --git a/docs/content/6.SocketCAN/Usage.md b/docs/content/6.SocketCAN/Usage.md new file mode 100644 index 0000000..d0ddf57 --- /dev/null +++ b/docs/content/6.SocketCAN/Usage.md @@ -0,0 +1,20 @@ +## SocketCAN + +[SocketCAN](https://github.com/linux-can/) is a set of open source CAN drivers and a networking stack contributed by Volkswagen Research to the Linux kernel. + +### 1. WiFi: +Change to protocol in the device configuration page to "slcan", then create a virtual serial port over TCP on your Linux machine. If WiCAN is connected to your home network replace "192.168.80.1" with device IP. + +``` +sudo socat pty,link=/dev/netcan0,raw tcp:192.168.80.1:3333 & +sudo slcand -o -c -s8 /dev/netcan0 can0 +sudo ifconfig can0 txqueuelen 1000 +sudo ifconfig can0 up +``` + +### 2. USB +``` +sudo slcand -o -s6 -t sw -S 4000000 /dev/ttyACM0 can0 +sudo ifconfig can0 txqueuelen 1000 +sudo ifconfig can0 up +``` diff --git a/docs/content/6.SocketCAN/_dir.yml b/docs/content/6.SocketCAN/_dir.yml new file mode 100644 index 0000000..5fb54fe --- /dev/null +++ b/docs/content/6.SocketCAN/_dir.yml @@ -0,0 +1,2 @@ +title: SocketCAN +icon: material-symbols:ecg diff --git a/docs/content/0.Config/2.MQTT.md b/docs/content/7.MQTT/Usage.md similarity index 56% rename from docs/content/0.Config/2.MQTT.md rename to docs/content/7.MQTT/Usage.md index a1cce66..0d9ce88 100644 --- a/docs/content/0.Config/2.MQTT.md +++ b/docs/content/7.MQTT/Usage.md @@ -1,96 +1,88 @@ -# MQTT +## CAN/ODBII over MQTT -Currently only non-secure MQTT is supported, it's highly recommended that you only use it with local MQTT broker and not use public brokers otherwise your CAN bus might be publicly exposed. +To exchange CAN messages via MQTT the [MQTT client has to be enabled and configured](../0.Config/1.WiFi.md). -![image](/config/mqtt/settings.png) +The [WiCAN device ID](../0.Config/1.WiFi.md) will also be needed to communicate with the device. -To use MQTT client simply Enable in the configuration page and fill in the broker details. You also need to note the device ID, which will be used to communicate with the device. The device ID "xxxxxxxxxxxx" is part of the AP ssid mentioned in [WiFi/CAN Configuration](/config/wifi) WiCAN_xxxxxxxxxxxx. This will alow you to communicate with multiple WiCAN device if needed. - -Example: If the AP ssid is "WiCAN_112233445566", the device ID is 112233445566. - -## 1. Status: +### 1. Status: When the device connects to the MQTT broker it will publish a status message to the status topic. -### - Status Topic: wican/xxxxxxxxxxxx/status -### - Status Message JSON: +- Topic: `wican/xxxxxxxxxxxx/status` +- Payload: `{"status": "offline"}`or `{"status": "online"}` -`{"status": "offline"} or {"status": "online"}` +### 2. Request CAN frames (TX): -## 2. MQTT TX RX Frame: +Request CAN frames have to follow this schema: +![image](/mqtt/transmit_json_schema.png) -``` -bus: Is always 0. Thats reserved for future application -type: tx or rx -dlc: 0 to 8 -rtr: true or false -extd: true or false -id: 11 or 29 bit ID -``` -**Example:** `{ "bus": "0", "type": "tx", "frame": [{ "id": 2015, "dlc": 8, "rtr": false, "extd": false, "data": [2, 1, 70, 170, 170, 170, 170, 170] }] };` +Explanations: +- **bus**: Is always 0. Reserved for future application +- **type**: tx or rx +- **dlc**: 0 to 8 +- **rtr**: true or false +- **extd**: true or false +- **id**: 11 or 29 bit ID -## 3. Receive Frames: +**Example:** +- Topic: wican/xxxxxxxxxxxx/can/tx +- Payload: `{ "bus": "0", "type": "tx", "frame": [{ "id": 2015, "dlc": 8, "rtr": false, "extd": false, "data": [2, 1, 70, 170, 170, 170, 170, 170] }] };` -To receive CAN frames simply subscribe to the receive topic. Each MQTT message might contain more than 1 frame. +### 3. Receive CAN Frames (RX) -### - Receive Topic: wican/xxxxxxxxxxxx/can/rx -### - Received Message JSON: +To receive CAN frames simply subscribe to the receive topic `wican/xxxxxxxxxxxx/can/rx`. Each MQTT message might contain more than 1 frame. -`{"bus":0,"type":"rx","ts":34610,"frame":[{"id":123,"dlc":8,"rtr":false,"extd":false,"data":[1,2,3,4,5,6,7,8]},{"id":124,"dlc":8,"rtr":false,"extd":true,"data":[1,2,3,4,5,6,7,8]}]}` -### - Received Message JSON Schema: -![image](/config/mqtt/recieve_json_schema.png) +Received messages follow this JSON schema: +![image](/mqtt/recieve_json_schema.png) -## 4. Transmit Frames: +**Example:** +- Topic: wican/xxxxxxxxxxxx/can/rx +- Payload: `{"bus":0,"type":"rx","ts":34610,"frame":[{"id":123,"dlc":8,"rtr":false,"extd":false,"data":[1,2,3,4,5,6,7,8]},{"id":124,"dlc":8,"rtr":false,"extd":true,"data":[1,2,3,4,5,6,7,8]}]}` -### - Transmit Topic: wican/xxxxxxxxxxxx/can/tx -### - Transmit Message JSON: -{"bus":0,"type":"tx","frame":[{"id":123,"dlc":8,"rtr":false,"extd":true,"data":[1,2,3,4,5,6,7,8]},{"id":124,"dlc":8,"rtr":false,"extd":true,"data":[1,2,3,4,5,6,7,8]}]} -### - Transmit Message JSON Schema: -![image](/config/mqtt/transmit_json_schema.png) +### 3. OBDII PID Request Over MQTT -## 5. OBDII PID Request Over MQTT +There is [list of standard PIDs](https://en.wikipedia.org/wiki/OBD-II_PIDs). -``` -bus: Is always 0. Reserved for future application -dlc: Always 8 -rtr: false -extd: false, if the car obd2 protocol is 11bit ID, 500 kbaud or 250 kbaud -extd: true, if the car obd2 protocol is 29bit ID, 500 kbaud or 250 kbaud -id: 11 bit OBD2 request ECU ID should be 2015 (that's 0x7DF in HEX) -id: 29 bit OBD2 request ECU ID should be 417018865 (that's 0x18DB33F1 in HEX) -``` +The frames meet the following criteria: +- **bus**: Is always 0. Reserved for future application +- **dlc**: Always 8 +- **rtr**: false +- **extd**: false, if the car obd2 protocol is 11bit ID, 500 kbaud or 250 kbaud +- **extd**: true, if the car obd2 protocol is 29bit ID, 500 kbaud or 250 kbaud +- **id**: 11 bit OBD2 request ECU ID should be 2015 (that's 0x7DF in HEX) +- **id**: 29 bit OBD2 request ECU ID should be 417018865 (that's 0x18DB33F1 in HEX) -![image](/config/mqtt/pid_request.png) +![image](/mqtt/pid_request.png) -### Example: Get ambient temp request, PID is 70 +#### Example: Ambient temperature +Get ambient temp request, PID is 70 + +##### Request +- Topic: wican/xxxxxxxxxxxx/can/tx +- Payload: `{ "bus": "0", "type": "tx", "frame": [{ "id": 2015, "dlc": 8, "rtr": false, "extd": false, "data": [2, 1, 70, 170, 170, 170, 170, 170] }] };` -`{ "bus": "0", "type": "tx", "frame": [{ "id": 2015, "dlc": 8, "rtr": false, "extd": false, "data": [2, 1, 70, 170, 170, 170, 170, 170] }] };` - -### [List of Standard PIDs](https://en.wikipedia.org/wiki/OBD-II_PIDs) - -## 6. Request Battery SoC MQTT Example +#### Example: Battery SoC This PID request should work on most EVs, **however it's not possible to know it will work on certain EV model unless it's tested on that specific car model**. -### Request - -`{"bus":"0","type":"tx","frame":[{"id":2015,"dlc":8,"rtr":false,"extd":false,"data":[2,1,91,170,170,170,170,170]}]}` - -### Response - -`{"bus":"0","type":"rx","ts":51561,"frame":[{"id":2024,"dlc":8,"rtr":false,"extd":false,"data":[3,65,91,**170**,0,0,0,0]}]}` +#### Request +- Topic: wican/xxxxxxxxxxxx/can/tx +- Payload: `{"bus":"0","type":"tx","frame":[{"id":2015,"dlc":8,"rtr":false,"extd":false,"data":[2,1,91,170,170,170,170,170]}]}` -`The SoC = (170 x 100)/255 = **66.67%**` +#### Response +- Topic: wican/xxxxxxxxxxxx/can/rx +- Payload: `{"bus":"0","type":"rx","ts":51561,"frame":[{"id":2024,"dlc":8,"rtr":false,"extd":false,"data":[3,65,91,**170**,0,0,0,0]}]}` -## 7. CAN to JSON interpreter - Filtering +The SoC is calculated as (170 x 100)/255 = **66.67%**. +### 4. CAN to JSON interpreter - Filtering This feature enables you to convert CAN messages into JSON format, apply calculations as specified by your expressions, and send the resulting data to an MQTT broker at predefined intervals. Below, we provide a comprehensive guide on how to effectively utilize this powerful feature. **Note: When a filter is added, all other CAN messages will be ignored, ensuring that only the configured filtered messages are sent.** -![image](/config/mqtt/filtering.png) +![image](/mqtt/filtering.png) ### Configuration Parameters: @@ -120,7 +112,7 @@ Define the mathematical operations to apply to the extracted value. It's crucial Specify the time interval in milliseconds between JSON messages sent to MQTT. The cycle time should fall within the range of 100 to 10,000 milliseconds. -### JSON Format +#### JSON Format WiCAN processes CAN frames, and the resulting JSON data follows this structure: @@ -135,14 +127,14 @@ WiCAN processes CAN frames, and the resulting JSON data follows this structure: Name|CAN ID| Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 ---|--- | --- | --- | --- |--- |--- |--- |--- |--- Engine Speed|2024| 4| 65| **12**| _18_| _52_| 170| 170| 170 -| | | | | PID| Value 1| Value 2 | | +| | | | | PID| Value 1| Value 2 | | The Engine Speed is PID response so "PID" must be set 12. The value we need to extract is 16bit in Byte 3 and Byte 4. So we set the "Start Bit" to 24 and "Bit Length" to 16. The extracted value will be (11 * 256)+68 = 4660. Now to get the engine speed in rpm we must multiple by 0.25. So the "Expression" will be V * 0.25= 1165 Name|CAN ID| Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 ---|--- | --- | --- | --- |--- |--- |--- |--- |--- Vehicle Speed|2024| 4| 65| **13**| _23_|170| 170| 170| 170 -| | | | | PID| Value 1| | | +| | | | | PID| Value 1| | | The Vehicle Speed is PID response so "PID" must be set 13. The value we need to extract is 8bit in Byte 3. So we set the "Start Bit" to 24 and "Bit Length" to 8. The extracted value will be 23. No need for any operation to get the speed so we set the "Expression" to V, so the value will be 23. diff --git a/docs/content/7.MQTT/_dir.yml b/docs/content/7.MQTT/_dir.yml new file mode 100644 index 0000000..7b6235d --- /dev/null +++ b/docs/content/7.MQTT/_dir.yml @@ -0,0 +1,2 @@ +title: CAN over MQTT +icon: material-symbols:compare-arrows diff --git a/docs/public/busmaster/vscan_api_device_config.png b/docs/public/busmaster/vscan_api_device_config.png new file mode 100644 index 0000000..ad81ec7 Binary files /dev/null and b/docs/public/busmaster/vscan_api_device_config.png differ diff --git a/docs/public/config/can.png b/docs/public/config/can.png new file mode 100644 index 0000000..e9a2141 Binary files /dev/null and b/docs/public/config/can.png differ diff --git a/docs/public/config/mqtt.png b/docs/public/config/mqtt.png new file mode 100644 index 0000000..f1b8429 Binary files /dev/null and b/docs/public/config/mqtt.png differ diff --git a/docs/public/config/mqtt/settings.png b/docs/public/config/mqtt/settings.png deleted file mode 100644 index b2696d0..0000000 Binary files a/docs/public/config/mqtt/settings.png and /dev/null differ diff --git a/docs/public/config/mqtt_enable.png b/docs/public/config/mqtt_enable.png new file mode 100644 index 0000000..8538a42 Binary files /dev/null and b/docs/public/config/mqtt_enable.png differ diff --git a/docs/public/config/mqtt/filtering.png b/docs/public/mqtt/filtering.png similarity index 100% rename from docs/public/config/mqtt/filtering.png rename to docs/public/mqtt/filtering.png diff --git a/docs/public/config/mqtt/pid_request.png b/docs/public/mqtt/pid_request.png similarity index 100% rename from docs/public/config/mqtt/pid_request.png rename to docs/public/mqtt/pid_request.png diff --git a/docs/public/config/mqtt/recieve_json_schema.png b/docs/public/mqtt/recieve_json_schema.png similarity index 100% rename from docs/public/config/mqtt/recieve_json_schema.png rename to docs/public/mqtt/recieve_json_schema.png diff --git a/docs/public/config/mqtt/transmit_json_schema.png b/docs/public/mqtt/transmit_json_schema.png similarity index 100% rename from docs/public/config/mqtt/transmit_json_schema.png rename to docs/public/mqtt/transmit_json_schema.png