Documentation

ArminJo · Jun 16, 2023 · 7fbaf02 · 7fbaf02
1 parent 3c67ab0
commit 7fbaf02
Show file tree

Hide file tree

Showing 5 changed files with 71 additions and 40 deletions.
diff --git a/.github/workflows/TestCompile.yml b/.github/workflows/TestCompile.yml
@@ -21,12 +21,29 @@ jobs:
   build:
     name: Test compiling examples for UNO
     runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        arduino-boards-fqbn:
+          - arduino:avr:uno
+          - arduino:avr:uno|CRYSTAL_20MHZ_ASSEMBLED
+          - arduino:avr:uno|LOCAL_DEBUG
+
+        include:
+          - arduino-boards-fqbn: arduino:avr:uno|CRYSTAL_20MHZ_ASSEMBLED
+            build-properties:
+              All: -DCRYSTAL_20MHZ_ASSEMBLED
+
+          - arduino-boards-fqbn: arduino:avr:uno|LOCAL_DEBUG
+            build-properties:
+              All: -DLOCAL_DEBUG
+
     steps:
       - name: Checkout
         uses: actions/checkout@master
 
       - name: Compile all examples
         uses: ArminJo/arduino-test-compile@master
-#        with:
+        with:
 #          required-libraries: EasyButtonAtInt01,SoftI2CMaster
-#          build-properties: -DCRYSTAL_20MHZ_ASSEMBLED
+          build-properties: ${{ toJson(matrix.build-properties) }}
diff --git a/JK-BMSToPylontechCAN/JK-BMS.h b/JK-BMSToPylontechCAN/JK-BMS.h
@@ -23,6 +23,16 @@
  *
  */
 
+/*
+ * The protocol at the display connector RS485 is 2400 baud 294 bytes in 1.2 seconds with a pause of 0.5 s.
+ * It starts with A5 5A 5D 82 10 00 0F 7C-7E
+ * at 0x16 there are 10 words 0F 7C-7F
+ * At 0x32 there are 46 bytes 0x00 for error flags, (tested with sensor over temperature resulting in a 01 at 0x57)
+ * At 0x60 there are 24 Values A5 5A 05 82 2 (0 0 to 1 7) 3 for 24 cell values
+ * of 16 bit each (for the status display page) followed by the END token A5 5A 03 80 01 00
+ *
+ *
+ */
 #ifndef _JK_BMS_H
 #define _JK_BMS_H
 

diff --git a/JK-BMSToPylontechCAN/JK-BMSToPylontechCAN.ino b/JK-BMSToPylontechCAN/JK-BMSToPylontechCAN.ino
@@ -14,11 +14,13 @@
  *  !!! So you must replace the crystal of the module with a 16 (or 20) MHz one !!!
  *  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  *
- *  Internal operation:
- *  1. A request is sent to the BMS.
+ *  Internal operation (every n seconds):
+ *  1. A request to deliver all informations is sent to the BMS.
  *  2. The BMS reply frame is stored in a buffer and parity and other plausi checks are made.
  *  3. The cell data are converted and enhanced to fill the JKConvertedCellInfoStruct.
- *  4. Other frame data are converted and enhanced to fill the JKComputedDataStruct.
+ *     Other frame data are mapped to a C structure.
+ *     But all words and longs in this structure are filled with big endian and thus cannot be read directly but must be swapped on reading.
+ *  4. Some other frame data are converted and enhanced to fill the JKComputedDataStruct.
  *  5. The content of the result frame is printed. After reset, all info is printed once, then only dynamic info is printed.
  *  6. The required CAN data is filled in the according PylontechCANFrameInfoStruct.
  *  7. Dynamic data and errors are displayed on the optional 2004 LCD if attached.
@@ -57,24 +59,24 @@
  *  You should have received a copy of the GNU General Public License
  *  along with this program. If not, see <http://www.gnu.org/licenses/gpl.html>.
  *
- UART-TTL
- __________                  _________
- |          |<----- RX ----->|         |
- |  JK-BMS  |<----- TX ----->|  UNO/   |
- |          |<----- GND ---->|  NANO   |<-- 5V
- |          |                |         |<-- GND
- |__________|                |_________|
-
- # UART-TTL socket (4 Pin, JST 1.25mm pitch)
- ___ ________ ___
- |                |
- | O   O   O   O  |
- |GND  RX  TX VBAT|
- |________________|
- |   |   |
- |   |   ----- RX
- |   --------- D4 (or other)
- --------------GND
+ * UART-TTL
+ *  __________                  _________            _________             _________
+ * |          |<----- RX ----->|         |<-- SPI ->|         |           |         |
+ * |  JK-BMS  |<----- TX ----->|  UNO/   |          | MCP2515 |           |         |
+ * |          |                |  NANO   |<-- 5V -->|   CAN   |<-- CAN -->|  DEYE   |
+ * |          |<----- GND ---->|         |<-- GND-->|         |           |         |
+ * |__________|                |_________|          |_________|           |_________|
+ *
+ * # UART-TTL socket (4 Pin, JST 1.25mm pitch)
+ *  ___ ________ ___
+ * |                |
+ * | O   O   O   O  |
+ * |GND  RX  TX VBAT|
+ * |________________|
+ *   |   |   |
+ *   |   |   ----- RX
+ *   |   --------- D4 (or other)
+ *   --------------GND
  */
 
 #include <Arduino.h>
@@ -116,7 +118,7 @@ bool sStaticInfoWasSent = false; // Flag to send static Info only once after res
 #include "SoftwareSerialTX.h"
 SoftwareSerialTX TxToJKBMS(4);          // Use a 115200 baud software serial for the short request frame
 bool sFrameIsRequested = false;         // If true, request was recently sent so now check for serial input
-uint32_t sMillisOfLastRequestedFrame = -MILLISECONDS_BETWEEN_JK_DATA_FRAME_REQUESTS; // // For BMS timing. Initial value to start first request immediately
+uint32_t sMillisOfLastRequestedJKDataFrame = -MILLISECONDS_BETWEEN_JK_DATA_FRAME_REQUESTS; // Initial value to start first request immediately
 uint32_t sMillisOfLastReceivedByte = 0; // For timeout
 bool sFrameHasTimeout = false;          // If true BMS is likely switched off.
 uint16_t sFrameTimeoutCounter = 0;
@@ -328,8 +330,8 @@ void loop() {
     /*
      * Request status frame every n seconds
      */
-    if (millis() - sMillisOfLastRequestedFrame >= MILLISECONDS_BETWEEN_JK_DATA_FRAME_REQUESTS) {
-        sMillisOfLastRequestedFrame = millis();
+    if (millis() - sMillisOfLastRequestedJKDataFrame >= MILLISECONDS_BETWEEN_JK_DATA_FRAME_REQUESTS) {
+        sMillisOfLastRequestedJKDataFrame = millis();
         /*
          * Flush input buffer and send request to JK-BMS
          */

diff --git a/JK-BMSToPylontechCAN/LiquidCrystal_I2C.hpp b/JK-BMSToPylontechCAN/LiquidCrystal_I2C.hpp
@@ -1,19 +1,19 @@
 // Based on the work by DFRobot
 
+#include "Arduino.h"
+
+#if defined(__AVR__) && !defined(USE_SOFT_I2C_MASTER) && __has_include("SoftI2CMasterConfig.h")
+#define USE_SOFT_I2C_MASTER // must be before #include "LiquidCrystal_I2C.h"
+#endif
+
 #include "LiquidCrystal_I2C.h"
 #include <inttypes.h>
 
-#include "Arduino.h"
-
 inline size_t LiquidCrystal_I2C::write(uint8_t value) {
     send(value, Rs);
     return 1;
 }
 
-#if !defined(USE_SOFT_I2C_MASTER) && __has_include("SoftI2CMasterConfig.h")
-#define USE_SOFT_I2C_MASTER
-#endif
-
 #if defined(USE_SOFT_I2C_MASTER)
 //#define USE_SOFT_I2C_MASTER_H_AS_PLAIN_INCLUDE
 #include "SoftI2CMasterConfig.h"    // Include configuration for sources

diff --git a/README.md b/README.md
@@ -44,15 +44,16 @@ The JK-BMS RS485 data (e.g. at connector GPS) are provided as RS232 TTL with 105
  <br/>
 
 # Principle of operation
-1. A request is sent to the BMS.
+1. A request to deliver all informations is sent to the BMS.
 2. The BMS reply frame is stored in a buffer and parity and other plausi checks are made.
 3. The cell data are converted and enhanced to fill the JKConvertedCellInfoStruct.
+   Other frame data are mapped to a C structure.
+   But all words and longs in this structure are filled with big endian and thus cannot be read directly but must be swapped on reading.
 4. Other frame data are converted and enhanced to fill the JKComputedDataStruct.
 5. The content of the result frame is printed. After reset, all info is printed once, then only dynamic info is printed.
 6. The required CAN data is filled in the according PylontechCANFrameInfoStruct.
 7. Dynamic data and errors are displayed on the optional 2004 LCD if attached.
 8. CAN data is sent.
-
 <br/>
 
 # Compile with the Arduino IDE
@@ -63,17 +64,17 @@ All libraries, especially the modified ones, are included in this project.
 This program uses the following libraries, which are included in this repository:
 
 - [SoftwareSerialTX](https://reference.arduino.cc/reference/en/libraries/liquidcrystal-i2c/) for sending Serial to JK-BMS.
-- Modified [LiquidCrystal_I2C]() for I2C connected LCD.
+- Modified [LiquidCrystal_I2C](https://reference.arduino.cc/reference/en/libraries/liquidcrystal-i2c/) for LCD connected by I2C.
+- [SoftI2CMaster](https://github.com/felias-fogg/SoftI2CMaster) for LCD minimal I2C functions.
 - [LCDBigNumbers](https://github.com/ArminJo/LCDBigNumbers) for LCD big number generation.
 - [EasyButtonAtInt01](https://github.com/ArminJo/EasyButtonAtInt01) for LCD page switching button.
-- [SoftI2CMaster](https://github.com/felias-fogg/SoftI2CMaster) for minimal I2C functions.
 - Modified mcp_can_dfs.h file from Seed-Studio [Seeed_Arduino_CAN](https://github.com/Seeed-Studio/Seeed_Arduino_CAN).
 
  <br/>
 
 # Disclaimer
-Currently (1.6.2023) the program is tested only with a JK-BMS JK-B2A20S20P and a 10 cell LiIon battery.<br/>
-It was not connected to a Deye inverter so far, since the target 16 cell LiFePo battery is stil on its way.
+Currently (16.6.2023) the program is tested only with a JK-BMS JK-B2A20S20P and a 10 cell LiIon battery.<br/>
+It was not connected to a Deye inverter so far, since the target 16 cell LiFePo battery is under contruction.
 
  <br/>
 
@@ -85,12 +86,13 @@ It was not connected to a Deye inverter so far, since the target 16 cell LiFePo
 - Shottky diode e.g. BAT 43.
 - Arduino Nano.
 - 16 (or 20) MHz crystal.
-- MCP2515 / TJA1050 kit for Arduino. !!! You must replace the assembled 8 MHz crystal with a 16 MHz one !!!
+- MCP2515 / TJA1050 kit for Arduino. !!! You must replace the assembled 8 MHz crystal with a 16 MHz (20 MHz) one !!!
 
 ### Optional
 - 2004 LCD with serial I2C interface adapter.
+- 2 pin female header for automatic LCD brightness control.
 - LDR for automatic LCD brightness control.
-- BC 549C or any type with hFe > 250 for automatic LCD brightness control.
+- BC 549C or any type with hFE > 250 for automatic LCD brightness control.
 
 <br/>