Skip to content

Commit

Permalink
Merge pull request #202 from jay-oswald/more-docs-update
Browse files Browse the repository at this point in the history 
More docs update
  • Loading branch information
@meatpiHQ
meatpiHQ authored Sep 11, 2024
2 parents fd37fc2 + 10ce69f commit 1cfa295
Show file tree
Hide file tree
Showing 16 changed files with 230 additions and 243 deletions.
244 changes: 1 addition & 243 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
## Please update to the [latest firmware version](https://github.com/meatpiHQ/wican-fw/releases/)
---
# [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)

Expand Down Expand Up @@ -41,14 +42,10 @@
---
## [webCAN](http://webcan.meatpi.com/) Coming soon!

- [Features Wishlist](#features-wishlist)
- [Important Notes](#important-notes)
- [API](#api)
- [Build](#build)
- [Description](#description)
- [Features](#features)
- [Sleep mode](#1-sleep-mode)
- [Battery Alert](#2-battery-alert)
- [Configuration](#configuration)
- [WiFi/CAN Configuration](#1-wifican-configuration)
- [BUSMaster](#2-busmaster)
Expand All @@ -59,28 +56,10 @@
- [WiFi](#1-wifi)
- [USB](#2-usb)
- [ELM327 OBD2 Protocol](#elm327-obd2-protocol)
- [MQTT](#mqtt)
- [Status](#1-status)
- [MQTT TX RX Frame](#2-mqtt-tx-rx-frame)
- [Receive Frames](#3-receive-frames)
- [Transmit Frames](#4-transmit-frames)
- [OBDII PID Request Over MQTT](#5-obdii-pid-request-over-mqtt)
- [Request Battery SoC MQTT Example](#6-request-battery-soc-mqtt-example)
- [CAN to JSON interpreter - Filtring](#7-can-to-json-interpreter---filtring)
- [Firmware Update](#firmware-update)
- [OTA](#1-ota)
- [USB Flash](#2-usb-flash)

# **Features Wishlist**:

- ~~CAN Auto baudrate~~ **DONE**
- ~~Support ELM327 OBD2 protocol~~ **DONE** (Basic support)
- ~~Home Assistant Integrations~~ **DONE**
- Extended ELM327 support
- Support ELM327 protocol and Realdash protocol simultaneously on WiFi and BLE
- Add option to send an Email on battery alert
- Expand alerts to include other CAN parameters parsed from DBC files.
- Support for extra wifi settings
# **Important Notes**:

- The OBD2 adapter is not designed to powered of the USB connecter. The USB connector can power the adapter to flash custom firmware or hardreset the deivce and can also be used for debuging.
Expand Down Expand Up @@ -134,20 +113,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")

# Features:
--------

## 1. Sleep Mode:

WiCAN can be permanently attached to the car without worrying about draining the battery. It monitors the battery voltage and can detect when the alternator is ON. When the engine is ON the battery continuously charging and the voltage will be about 13.5V(can vary with different car models). When the engine is OFF the battery voltage drops to about 12.8V(full battery) - WiCAN can detect this drop, and if the voltage remains under the threshold for **3 min** it will go to sleep and the current consumption will drop below **1mA**. If the engine is turned ON it will immediately wake up and enable the WiFi/BLE.
The threshold voltage is configurable and can be set in the configuration page, the default value is 13V.

## 2. Battery Alert:

This is an important feature for most car enthusiast who own multiple cars that are only driven few times a year. Basically if a car is not used in few month the battery will go flat and needs to be jumped. WiCAN can be configured to send an alert when the battery voltage drops under a certain level. Sleep mode has to be enabled for this feature to be useful. **For now alerts can be sent on MQTT, more protocols are coming soon. If there is a specific protocol you want to be supported let me know.**

![image](https://user-images.githubusercontent.com/94690098/182034543-8025c5ab-5e38-43a0-9ec8-014d4301fcf0.png)

# Configuration:
--------

Expand Down Expand Up @@ -279,213 +244,6 @@ sudo ifconfig can0 up
7. Activate ``` Request Only First Reply ```
8. Click Done.

# MQTT

## 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 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.

![image](https://user-images.githubusercontent.com/94690098/196186799-7299fe23-8d98-40e0-ad72-a4aeaf695110.png)

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](#1-wifican-configuration) 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:

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:

{"status": "offline"} or {"status": "online"}

## 2. MQTT TX RX Frame:

```
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] }] };

## 3. Receive Frames:

To receive CAN frames simply subscribe to the receive topic. Each MQTT message might contain more than 1 frame.

### - Receive Topic: wican/xxxxxxxxxxxx/can/rx
### - Received Message JSON:

{"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](https://user-images.githubusercontent.com/94690098/196184692-40c84504-580c-449f-9876-3d373dd11560.png)

## 4. Transmit Frames:

### - 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](https://user-images.githubusercontent.com/94690098/196187228-3923204e-1b87-4ece-bb72-406e338a5831.png)

## 5. OBDII PID Request Over MQTT

```
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](https://github.com/meatpiHQ/wican-fw/assets/94690098/7726d4fe-1d6f-4b1e-be93-ea4304a47942)

### Example: Get ambient temp request, PID is 70

{ "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

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]}]}

The SoC = (170 x 100)/255 = **66.67%**

## 7. 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.**

<img width="1496" alt="image" src="https://github.com/meatpiHQ/wican-fw/assets/94690098/18e87820-2b5f-4823-947d-0d1c412a6e3d">


### Configuration Parameters:

**CAN ID: Frame ID in DEC**
This parameter refers to the CAN message identifier in decimal format.

**Name**
Specify the JSON key under which the extracted value will be stored.

**PID: PID Number in DEC**
If the frame is a response to a PID request, set this parameter to the relevant PID number. Otherwise, for non-PID frames, it should be set to -1.

**Index: PID index**
For all standard PID requests, this should be set to 2, referring to byte 2 in the response. In certain special cases, this value may differ from 2. If the PID is set to -1, the interpreter will disregard this value.

**Start Bit**
Indicate the bit from which you want to commence extracting the value. For instance, if Byte 0 is represented as 0xA0 in binary (b1010 0000), 'Bit 0' would correspond to 1, 'Bit 1' to 0, and so forth.

**Bit Length**
This parameter denotes the number of bits comprising the value you intend to extract.

**Expression**
Define the mathematical operations to apply to the extracted value. It's crucial to include the letter 'V' to represent the extracted value within your expression.

**Cycle**
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

WiCAN processes CAN frames, and the resulting JSON data follows this structure:

```
{"VehicleSpeed": 23.000000}
{"EngineSpeed": 1165.000000}
{"CustomID": 3594.400000}
```

### PID response frames Example:

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 | |

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| | |

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.

### Other CAN Frames Example:

Name|CAN ID| Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7
---|--- | --- | --- | --- |--- |--- |--- |--- |---
Custom ID|356| 170| 170| _35_| _16_|170| 170| 170| 170

The PID in the configuration needs to set to -1. The value we need to extract is 16bit in Byte 2 and Byte 3. So we set the "Start Bit" to 16 and "Bit Length" to 16. The extracted value will be (35*256)+16 = 8976. Now to get the value we must add 10 to the Value and divide by 2.5. So the "Expression" will be (V+10)/2.5 = 3594.4

Name|CAN ID| Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7
---|--- | --- | --- | --- |--- |--- |--- |--- |---
Custom ID|355| 170| 170| 170| 170|_5_| _34_| 170| 170

The PID in the configuration should be set to -1. The values to extract are from Byte 4 and Byte 5. The formula used here is (5 + 34)/2, so the expression to set is (B4 + B5)/2.

# Firmware Update

## 1. OTA:
1. Download the latest release version, or compile your own.
1. Go the device [configuration page](#device-configuration).
2. Click on the "About" tab.
3. Click on "Choose File".
4. Select the binary file. Eample: wican-fw_v130.bin
5. Click update, update should take about 30sec.

**NOTE: After flashing, the device configuration might be erased.**

**Note: for firmware version v1.00 use USB cable to flash the unit.**

<img src="https://user-images.githubusercontent.com/94690098/163678507-f9822f57-bbe1-42a4-82c4-501cd7834ba0.png" width="350" height="300" >

## 2. USB Flash:

Use the [**ESP flash tool**](https://www.espressif.com/en/support/download/other-tools) to update the firmware, just follow the same setting in the picture below. Make sure to select ESP32-C3 and USB mode. **esptool.py** also can also be used to flash a new firmware.
1. Download [**ESP flash tool**](https://www.espressif.com/en/support/download/other-tools)
2. Download the latest firmware zip file from the [**releases**](https://github.com/meatpiHQ/wican-fw/releases) page.
3. Select ESP32C3, develop and USB then click ok

![image](https://user-images.githubusercontent.com/94690098/182028074-7cd55122-a129-4fd3-bad9-e66f1f8d3ca3.png)

4. Set the configuration as the picture below, select and fill in the address for each binary.

<img src="https://user-images.githubusercontent.com/94690098/182028212-e8e90e71-7758-4d2d-88dc-aebf95a2e4a8.png" width="350" height="600" >

5. Short the pins as shown, then plug in the USB cable.

### OBD
![image](https://user-images.githubusercontent.com/94690098/182028671-18d523de-466d-4c28-998d-c4330dd33ae7.png)

### USB
![image](https://github.com/meatpiHQ/wican-fw/assets/94690098/b9c9fe35-6ec1-4a64-8753-134fabd43c0c)


6. After you plug in the USB cable the Orange LED will light up. Now click START button on the flash tool.

**NOTE: After flashing, the device configuration might be erased.**


---

© 2023 meatPi Electronics | www.meatpi.com | PO Box 5005 Clayton, VIC 3168, Australia
42 changes: 42 additions & 0 deletions docs/content/0.Config/Firmware-Update.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Firmware Update

## 1. OTA:
1. Download the latest release version, or compile your own.
1. Go the device [configuration page](#device-configuration).
2. Click on the "About" tab.
3. Click on "Choose File".
4. Select the binary file. Eample: wican-fw_v130.bin
5. Click update, update should take about 30sec.

**NOTE: After flashing, the device configuration might be erased.**

**Note: for firmware version v1.00 use USB cable to flash the unit.**

![image](/config/firmware/about.png)

## 2. USB Flash:

Use the [**ESP flash tool**](https://www.espressif.com/en/support/download/other-tools) to update the firmware, just follow the same setting in the picture below. Make sure to select ESP32-C3 and USB mode. **esptool.py** also can also be used to flash a new firmware.
1. Download [**ESP flash tool**](https://www.espressif.com/en/support/download/other-tools)
2. Download the latest firmware zip file from the [**releases**](https://github.com/meatpiHQ/wican-fw/releases) page.
3. Select ESP32C3, develop and USB then click ok

![image](/config/firmware/flash-select.png)

4. Set the configuration as the picture below, select and fill in the address for each binary.

![image](/config/firmware/flash-config.png)

5. Short the pins as shown, then plug in the USB cable.

### OBD
![image](/config/firmware/obd.png)

### USB
![image](/config/firmware/usb.png)


6. After you plug in the USB cable the Orange LED will light up. Now click START button on the flash tool.

**NOTE: After flashing, the device configuration might be erased.**

Loading

0 comments on commit 1cfa295

Please sign in to comment.