tsys01/STM32/TSYS_controller/Readme.md

# Firmware for controllers of thermal sensors
Network of up to 8 controllers (potentially you can use up to 16 but with some source code changes) for TSYS-01 thermal
sensors (up to 16 sensors per controller).

## Serial interface commands (ends with '\n'), small letter for only local processing:
- **0...7**  send message to Nth controller, not broadcast (after number should be CAN command)
- **@**  set/reset debug mode
- **A**  allow given node to speak
- **a**  get raw ADC values
- **B**  send dummy CAN messages to broadcast address
- **b**  get/set CAN bus baudrate
- **c**  show coefficients for all thermosensors
- **D**  send dummy CAN messages to master (0) address
- **d**  get current CAN address of device
- **Ee** end temperature scan
- **Ff** turn sensors off
- **g**  sniffer CAN mode (print to USB terminal all incoming CAN messages with alien IDs)
- **Hh** switch I2C to high speed (100kHz)
- **Ii** (re)init sensors
- **Jj** get MCU temperature
- **Kk** get values of U and I
- **Ll** switch I2C to low speed (default, 10kHz)
- **N**  get build number
- **Oo** turn onboard diagnostic LEDs **O**n or **o**ff (both commands are local!)
- **P**  ping everyone over CAN
- **Qq** get system time
- **Rr** reinit I2C
- **S**  shut up given node
- **s**  send CAN message (format: ID data[0..8], dec, 0x - hex, 0b - binary)
- **Tt** start single temperature measurement
- **U**  USB status of given node (0 - off)
- **u**  unique ID (default) CAN mode
- **Vv** very low speed
- **Xx** go into temperature scan mode
- **Yy** get sensors state over CAN (data format: 3 - state, 4,5 - presense mask [0,1], 6 - npresent, 7 - ntempmeasured
- **z**  check CAN status for errors

All capitall letters (except `O`) is CAN-bus commands. Any CAN-bus command should be started from node number. The
message will be sent to given node and it will answer to inquiring node.

## PINOUT
- **I2C**: PB6 (SCL) & PB7 (SDA)
- **USART1**: PA9 (Tx) & PA10 (Rx) - DEPRECATED
- **CAN bus**: PB8 (Rx), PB9 (Tx)
- **USB bus**: PA11 (DM), PA12 (DP)
- **I2C multiplexer**: PB0..PB2 (0..2 address bits), PB12 (~EN)
- **sensors' power**: PB3 (in, overcurrent), PA8 (out, enable power)
- **signal LEDs**: PB10 (LED0), PB11 (LED1)
- **ADC inputs**: PA0 (V12/4.93), PA1 (V5/2), PA3 (I12 - 1V/A), PA6 (V3.3/2)
- **controller CAN address**: PA13..PA15 (0..2 bits), PB15 (3rd bit); 0 - master, other address - slave


## LEDS
- LED0 (nearest to sensors' connectors) - heartbeat
- LED1 (above LED0) - CAN bus OK

## CAN protocol
Variable data length: from 1 to 8 bytes.

CAN ID = 0x680 + Controller address (0..15). Controller with address = 0 is master, it translate
all incoming CAN traffic into USB and can send commands to different slaves. Slave answers with its ID.
Broadcast messages with ID=0 are ignored.

### Commands and data format
- byte 0 - command mark (0xA5) or data mark (0x5A);
- byte 1 - controller number (packet sender both for command or data);
- byte 2 - command code;
- bytes 3..7 - data (answer of command with DATA mark in byte 0).

So if you want to send command with code `xx` to node `N` from node `M`, you should send sequence of bytes with ID=`0x680+N`: 

    0xA5 M xx
    
And you will give answer with ID=`0x680+M`:

    0x5A N xx [up to 5 data bytes]

### Common commands
-    `CMD_PING`                (0)  request for PONG cmd
-    `CMD_START_MEASUREMENT`   (1)  start single temperature measurement
-    `CMD_SENSORS_STATE`       (2)  get sensors state
-    `CMD_START_SCAN`          (3)  run scan mode 
-    `CMD_STOP_SCAN`           (4)  stop scan mode
-    `CMD_SENSORS_OFF`         (5)  turn off power of sensors
-    `CMD_LOWEST_SPEED`        (6)  lowest I2C speed
-    `CMD_LOW_SPEED`           (7)  low I2C speed (10kHz)
-    `CMD_HIGH_SPEED`          (8)  high I2C speed (100kHz)
-    `CMD_REINIT_I2C`          (9)  reinit I2C with current speed
-    `CMD_CHANGE_MASTER_B`     (10) change master id to broadcast
-    `CMD_CHANGE_MASTER`       (11) change master id to 0
-    `CMD_GETMCUTEMP`          (12) MCU temperature value
-    `CMD_GETUIVAL`            (13) request to get values of V12, V5, I12 and V3.3
-    `CMD_GETUIVAL0`           (14) answer with values of V12 and V5
-    `CMD_GETUIVAL1`           (15) answer with values of I12 and V3.3
-    `CMD_REINIT_SENSORS`      (16) (re)init all sensors (discover all and get calibrated data)
-    `CMD_GETBUILDNO`          (17) get by CAN firmware build number (uint32_t, littleendian, starting from byte #4)
-    `CMD_SYSTIME`             (18) get system time in ms (uint32_t, littleendian, starting from byte #4)
-    `CMD_USBSTATUS`           (19) get slave's USB status (byte 3 of answer is 0/1 meaning USB inactive/active)
-    `CMD_SHUTUP`              (20) don't send anything into CAN bus (only CMD)
-    `CMD_SPEAK`               (21) normal working mode (only CMD)

### Answer for commands that don't need data
(can be only with DATA mark)
-    `CMD_ANSOK` = 0xAA 

### Dummy commands for test purposes
(can be only with CMD mark)
-    `CMD_DUMMY0` = 0xDA,
-    `CMD_DUMMY1` = 0xAD


### Thermal data format
- byte 3 - Sensor number (10*N + M, where N is multiplexer number, M - number of sensor in pair, i.e. 0,1,10,11,20,21...70,71)
- byte 4 - thermal data H
- byte 5 - thermal data L

### Sensors state data format
- byte 3 - Sstate value:
  -   `SENS_INITING`      (0) - start of init procedure
  -   `SENS_RESETING`     (1) - reset all sensors
  -   `SENS_GET_COEFFS`   (2) - gathering of calibration coefficients
  -   `SENS_SLEEPING`     (3) - sleeping
  -   `SENS_START_MSRMNT` (4) - starting next measurement
  -   `SENS_WAITING`      (5) - waitint for results
  -   `SENS_GATHERING`    (6) - collecting thermal data
  -   `SENS_OFF`          (7) - powered off by request
  -   `SENS_OVERCURNT`    (8) - overcurrent detected when trying to power on
  -   `SENS_OVERCURNT_OFF`(9) - overcurrend detected all 32 tries to power on sensors; sensors are powered off
- byte 4 - `sens_present[0]` value (Nth bit is 1 if sensor 0N found)
- byte 5 - `sens_present[1]` value (Nth bit is 1 if sensor 1N found)
- byte 6 - `Nsens_present` value
- byte 7 - `Ntemp_measured` value

### MCU temperature data format
- byte 3 - data H
- byte 4 - data L

All temperature is in degrC/100!

### U and I data format
- byte 2 - type of data (`CMD_GETUIVAL0` - V12 and V5, `CMD_GETUIVAL1` - I12 and V3.3)

case CMD_GETUIVAL0

- bytes 3,4 - V12 H/L
- bytes 5,6 - V5 H/L

case CMD_GETUIVAL1

- bytes 3,4 - I12 H/L
- bytes 5,6 - V33 H/L

Voltage is in V/100, Current is in mA