Added some examples how to use the lib

Author: Max 'MaxMax' Mönikes

examples/TLE9012_Library/TLE9012_Library.ino renamed to examples/Direct_Register_Access/Direct_Register_Access.ino

@@ -24,50 +24,60 @@ SOFTWARE.
 
 
 #include "TLE9012.h"
-//#include <Serial.h>
+#include "TLE9012_Makros.h"
 
+#define TXPIN 17
+#define RXPIN 16
 
 TLE9012 tle9012;
 
-ntc_config_t ntc_config = {.ntc_resistance=100000,.ntc_b_value=3000};
 
+/**
+ * This Example illustrates how to use low level register access to implement functionallity with no
+ * corresponding higher level library function.
+ * 
+ * This example was written for a ESP32-Node MCU Development Board
+ */
 
 void setup() {
-  // put your setup code here, to run once:
-  tle9012.init(&Serial2, 2000000,16,17);
+  
+  //To keep the example short, the initilization is performed using higher level functions
+  tle9012.init(&Serial2, 2000000,RXPIN,TXPIN);
   Serial.begin(115200);
   Serial.println("Boot completed");
   tle9012.wakeUp();
   delay(200);
-  tle9012.setExtendedWatchdog(0);
+
   tle9012.setNodeID(0, 1, 1);
   tle9012.writeMailboxRegister(1, 0xAA55);
 
   uint16_t mailbox = tle9012.readMailboxRegister(1);
   if(mailbox == 0xAA55)
-    Serial.println("Mailbox Check completed");
+    Serial.println("Connection Check completed");
+
+  tle9012.writeRegisterSingle(1,PART_CONFIG,0x0FFF); // Set Part Config Register 
 
-  tle9012.setNumberofCells(1, 12);
-  tle9012.setTempSensorsConfig(1, 5, ntc_config);
-  uint16_t ptconf = 0;
-  tle9012.readRegisterSingle(1, 0x01, &ptconf);
-  Serial.println(ptconf);
 }
 
 void loop() {
 
   // put your main code here, to run repeatedly:
-  tle9012.readTemperatures(1);
-  for(uint8_t n = 0; n < 5; n++)
+  tle9012.writeRegisterBroadcast(WDOG_CNT,0x007F); // Broadcast Write Command to reset Watchdog Counter
+
+  tle9012.writeRegisterSingle(1, MEAS_CTRL, 0xEE61); //Start cell measurement
+  delay(10); //Wait till measurement is completed
+
+  uint16_t cell0_voltage = 0; 
+  iso_uart_status_t status = isoUART_OK;
+
+  status = tle9012.readRegisterSingle(1,PCVM_0,&cell0_voltage); //Read cell voltage and communication status
+
+  //Check if the bus action was transfered successfully
+  if(status != isoUART_OK)
   {
-    Serial.println("-------------------------------------------");
-    Serial.print("Resistance ");
-    Serial.print(n+1);
-    Serial.print(" : ");
-    Serial.print(tle9012.devices[0].ntc_resistances[n]);
-    Serial.print("\n");
-    Serial.println("-------------------------------------------");
+    Serial.print("Error during bus communication");
   }
+
   delay(1000);
 
 }

examples/Error_Handling/Error_Handling.ino

@@ -0,0 +1,109 @@
+/*
+MIT License
+
+Copyright (c) 2024 Maximilian Mönikes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+
+#include "TLE9012.h"
+
+
+#define N_CELLS 12
+#define TXPIN 17
+#define RXPIN 16
+
+#define OVERVOLTAGE_THRESHOLD 4.2
+#define UNDERVOLTAGE_THRESHOLD 2.5
+
+TLE9012 tle9012;
+
+/**
+ * This example shows how to register error handlers and perform periodic checks
+ * 
+ */
+
+void setup() {
+
+  tle9012.init(&Serial2, 2000000,RXPIN,TXPIN); //Initialize driver with 2Mbit
+
+  Serial.begin(115200);
+  Serial.println("Boot completed");
+
+  tle9012.wakeUp(); //Issue wakeup command
+  delay(200); //Wait some time to ensure wakeup was completed
+
+  tle9012.setNodeID(0, 1, 1); //Set device address from 0 to 1 and set device 1 as final Node
+
+  tle9012.writeMailboxRegister(1, 0xAA55);  //Write and Readback Mailbox register to check if communication works
+  uint16_t mailbox = tle9012.readMailboxRegister(1);
+
+  if(mailbox == 0xAA55) //Show Successfull communication
+    Serial.println("Connection Check completed");
+
+  tle9012.setNumberofCells(1, N_CELLS); //Configure the number of cells
+
+  tle9012.setOvervoltageThreshold(1,VOLTAGE_TO_OV_UV_LIMIT(OVERVOLTAGE_THRESHOLD)); //Set voltage Limits
+  tle9012.setUndervoltageThreshold(1,VOLTAGE_TO_OV_UV_LIMIT(UNDERVOLTAGE_THRESHOLD));
+
+  tle9012.attachErrorHandler(UNDERVOLTAGE_ERROR,underVoltageErrorHandler);  //Register Error Handlers
+  tle9012.attachErrorHandler(OVERVOLTAGE_ERROR,overVoltageErrorHandler);
+  tle9012.resetWatchdog(); //Reset Watchdog Timer
+
+}
+
+void loop() {
+  
+  tle9012.resetWatchdog();  //Reset Watchdog Timer
+  tle9012.readCellVoltages(1); //Optional -> Read out cell voltages. Errors will trigger independent of this measurement
+  tle9012.checkErrors(1); //Check for Errors and Call Handlers
+  
+  delay(1000);
+}
+
+/**
+ * @brief Error handler function that gets called in case of undervoltage errors
+ * 
+ * @param nodeID address of the device with a fault
+ * @param uv_flags bitmask containing what cells are below the undervoltage threshold
+ */
+void underVoltageErrorHandler(uint8_t nodeID, uint16_t uv_flags)
+{
+  Serial.println("Undervoltage Error Detected");
+  Serial.print("Undervoltage Flag Mask: ");
+  Serial.println(uv_flags,BIN);
+  tle9012.resetErrors(1);
+}
+
+
+/**
+ * @brief Error handler function that gets called in case of overvoltage errors
+ * 
+ * @param nodeID address of the device with a fault
+ * @param uv_flags bitmask containing what cells are above the overvoltage threshold
+ */
+
+void overVoltageErrorHandler(uint8_t nodeID, uint16_t ov_flags)
+{
+  Serial.println("Overvoltage Error Detected");
+  Serial.print("Overvoltage Flag Mask: ");
+  Serial.println(ov_flags,BIN);
+  tle9012.resetErrors(1);
+}

examples/Read_Temperatures/Read_Temperatures.ino

@@ -0,0 +1,87 @@
+/*
+MIT License
+
+Copyright (c) 2024 Maximilian Mönikes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+
+#include "TLE9012.h"
+#include <math.h>
+
+#define TXPIN 17
+#define RXPIN 16
+#define N_TEMPS 5
+
+TLE9012 tle9012;
+
+ntc_config_t ntc_cfg = {.ntc_resistance=1000,.ntc_b_value=3348 ,.basetemp = 298.15};
+
+void setup() {
+
+  tle9012.init(&Serial2, 2000000,RXPIN,TXPIN); //Initialize driver with 2Mbit
+
+  Serial.begin(115200);
+  Serial.println("Boot completed");
+
+  tle9012.wakeUp(); //Issue wakeup command
+  delay(200); //Wait some time to ensure wakeup was completed
+
+  tle9012.setNodeID(0, 1, 1); //Set device address from 0 to 1 and set device 1 as final Node
+
+  tle9012.writeMailboxRegister(1, 0xAA55);  //Write and Readback Mailbox register to check if communication works
+  uint16_t mailbox = tle9012.readMailboxRegister(1);
+
+  if(mailbox == 0xAA55) //Show Successfull communication
+    Serial.println("Connection Check completed");
+
+  tle9012.setTempSensorsConfig(1,N_TEMPS,ntc_cfg); //Set temperature sensor config
+  tle9012.resetWatchdog(); //Reset Watchdog Timer
+
+}
+
+void loop() {
+  
+  tle9012.resetWatchdog(); //Reset Watchdog Timer
+  tle9012.readTemperatures(1); //Measure Temperatures
+
+  for(uint8_t n = 0; n < N_TEMPS; n++) //Convert and Print Temperature over Serial
+  {
+    float ntc_resistance = NTC_MEASUREMENT_TO_R(tle9012.devices[0].ntc_resistances[n],100); //get ntc resistance assuming 100 Ohm Rf for NTC
+    Serial.print("NTC Resistance: ");
+    Serial.print(ntc_resistance);
+    Serial.print("Ohm  |  Temperature: ");
+    float temperature = r_to_temp(ntc_cfg,ntc_resistance); //Calculate temperature from ntc resistance
+    Serial.print(temperature);
+    Serial.println("°C");
+  }
+  Serial.println("-----------------------------------------------------------------------");
+
+  delay(1000);
+}
+
+/**
+ * This function is deliberatly not included in the library to prevent a forced inclusion of math.h
+ */
+
+float r_to_temp(ntc_config_t cfg, float resistance)
+{
+  return 1/((log(resistance/cfg.ntc_resistance)/cfg.ntc_b_value) + (1/cfg.basetemp))-273.15;
+}

examples/Read_Voltages/Read_Voltages.ino

@@ -0,0 +1,80 @@
+/*
+MIT License
+
+Copyright (c) 2024 Maximilian Mönikes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+
+#include "TLE9012.h"
+
+#define N_CELLS 12
+#define TXPIN 17
+#define RXPIN 16
+
+TLE9012 tle9012;
+
+/**
+ * This Example shows how to do a basic configuration of a single TLE9012 and read cell voltages
+ * 
+ */
+
+void setup() {
+  
+
+  tle9012.init(&Serial2, 2000000,RXPIN,TXPIN); //Initialize driver with 2Mbit
+
+  Serial.begin(115200);
+  Serial.println("Boot completed");
+
+  tle9012.wakeUp(); //Issue wakeup command
+  delay(200); //Wait some time to ensure wakeup was completed
+
+  tle9012.setNodeID(0, 1, 1); //Set device address from 0 to 1 and set device 1 as final Node
+
+  tle9012.writeMailboxRegister(1, 0xAA55);  //Write and Readback Mailbox register to check if communication works
+  uint16_t mailbox = tle9012.readMailboxRegister(1);
+
+  if(mailbox == 0xAA55) //Show Successfull communication
+    Serial.println("Connection Check completed");
+
+  tle9012.setNumberofCells(1, N_CELLS); //Configure the number of cells
+  tle9012.resetWatchdog(); //Reset Watchdog Timer
+
+}
+
+void loop() {
+  
+  tle9012.resetWatchdog(); //Reset Watchdog Timer
+  tle9012.readCellVoltages(1);  //Read all cell voltages from device 1
+
+  for(uint8_t n = 0; n < N_CELLS; n++)  //Print cell voltages to Serial Monitor
+  {
+    Serial.print("Cell Voltage ");
+    Serial.print(n+1);
+    Serial.print(": ");
+    Serial.println(ADCVALUE_TO_FLOAT_VOLTAGE(tle9012.devices[0].cell_voltages[n]));
+  }
+
+  Serial.println("-------------------------------------------------");
+
+  delay(1000);
+
+}