1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
//! Allows to read the current temperature from the TSIC 306 //! //! Note that most of this code is ported and heavily modified from C //! to rust using the code found in [arduino-tsic](https://github.com/Schm1tz1/arduino-tsic) //! and other places scattered throughout the internet that used the sensor //! from C. //! //! Please also refer to the [Data Sheet](https://www.ist-ag.com/sites/default/files/DTTSic20x_30x_E.pdf) //! for implementation details. //! //! ## Usage //! //! ```ignore //! use tsic::Tsic; //! //! let sensor = Tsic::new(/* your hal pin */); //! //! let mut delay = /* your hal delay */(); //! //! match sensor.read(&mut delay) { //! Ok(t) => defmt::info!("Temp is: {:f32}", t.as_celsius()), //! Err(e) => defmt::warn!("Getting sensor data failed: {:?}", e), //! }; //! ``` #![forbid(unsafe_code)] #![no_std] #![doc(html_root_url = "https://docs.rs/tsic/0.1.0")] #![warn(missing_docs, rust_2018_idioms, unused_qualifications)] use core::time::Duration; use embedded_hal::blocking::delay::DelayUs; use embedded_hal::digital::v2::InputPin; /// The spec defines the sample rate as 128kHz, which is 7.8 microseconds. Since /// we can only sleep for a round number of micros, 8 micros should be close enough. static STROBE_SAMPLING_RATE: Duration = Duration::from_micros(8); /// The `Tsic` struct is the main entry point when trying to get a temperature reading from a /// TSIC 306 sensor. pub struct Tsic<I: InputPin> { pin: I, } impl<I: InputPin> Tsic<I> { /// Creates a new `Tsic` sensor wrapper and binds it to the input pin given. pub fn new(pin: I) -> Self { Self { pin } } /// Attempts to read from the sensor, might fail (see errors for details if so). /// /// Note that the passed in `Delay` from the HAL needs to be aquired outside of /// this struct and passed in as mutable, because to aquire correct data from the /// sensor the code needs to pause for a certain amount of microseconds. pub fn read<D: DelayUs<u8>>(&self, delay: &mut D) -> Result<Temperature, TsicReadError> { let first_packet = self.read_packet(delay)?; let second_packet = self.read_packet(delay)?; Ok(Temperature::new(first_packet, second_packet)) } /// Reads the bits off of the sensor port based on the ZACWire protocol. /// /// From the documentation of the sensor: /// /// When the falling edge of the start bit occurs, measure the time until the /// rising edge of the start bit. This time is the strobe time. /// When the next falling edge occurs, wait for a time period equal to /// the strobe time, and then sample the signal. The data present on the signal /// at this time is the bit being transmitted. Because every bit starts /// with a falling edge, the sampling window is reset with every bit /// transmission. This means errors will not accrue for bits downstream /// from the start bit, as it would with a protocol such as RS232. It is /// recommended, however, that the sampling rate of the signal when acquiring /// the start bit be at least 16x the nominal baud rate. Because the nominal /// baud rate is 8kHz, a 128kHz sampling rate is recommended when acquiring the /// strobe time. /// /// See https://www.ist-ag.com/sites/default/files/ATTSic_E.pdf for /// the full document. fn read_packet<D: DelayUs<u8>>(&self, delay: &mut D) -> Result<Packet, TsicReadError> { self.wait_until_low()?; let strobe_len = self.strobe_len(delay)?.as_micros() as u8; let mut packet_bits: u16 = 0; for _ in 0..9 { self.wait_until_low()?; delay.delay_us(strobe_len); packet_bits <<= 1; if self.is_high()? { packet_bits |= 1; } self.wait_until_high()?; } Packet::new(packet_bits) } /// Measures the strobe length of the sensor. /// /// According to docs and other code, depending on the temperature the sensor /// can change its strobe length so to be sure we'll just check it before every /// read attempt. /// /// The strobe length should be around 60 microseconds. fn strobe_len<D: DelayUs<u8>>(&self, delay: &mut D) -> Result<Duration, TsicReadError> { let sampling_rate = STROBE_SAMPLING_RATE.as_micros(); let mut strobe_len = 0; while self.is_low()? { strobe_len += sampling_rate; delay.delay_us(sampling_rate as u8); } Ok(Duration::from_micros(strobe_len as u64)) } /// Checks if the pin is currently in a high state. fn is_high(&self) -> Result<bool, TsicReadError> { self.pin.is_high().map_err(|_| TsicReadError::PinReadError) } /// Checks if the pin is currently in a low state. fn is_low(&self) -> Result<bool, TsicReadError> { self.pin.is_low().map_err(|_| TsicReadError::PinReadError) } /// Returns only once the pin is in a low state. fn wait_until_low(&self) -> Result<(), TsicReadError> { while self.is_high()? {} Ok(()) } /// Returns only once the pin is in a high state. fn wait_until_high(&self) -> Result<(), TsicReadError> { while self.is_low()? {} Ok(()) } } /// Contains all errors that can happen during a reading from the sensor. #[derive(Debug)] pub enum TsicReadError { /// The parity check for one of the packets failed. /// /// This might be a temporary issue, so attempting to perform another /// read might resolve the error. ParityCheckFailed, /// Failed to read the high/low state of the pin. PinReadError, } /// Represents a single temperature reading from the TSIC 306 sensor. pub struct Temperature { raw: u16, } impl Temperature { /// Create a full temperature reading from the two individual half reading packets. fn new(first: Packet, second: Packet) -> Self { let raw = ((first.value() as u16) << 8) | second.value() as u16; Self { raw } } /// Returns the temperature in degree celsius. pub fn as_celsius(&self) -> f32 { (self.raw as f32 * 200.0 / 2047.0) - 50.0 } } /// A `Packet` represents one half of the full temperature measurement. struct Packet { raw_bits: u16, } impl Packet { /// Creates a new `Packet` from the raw measured bits. /// /// Note that this method performs a parity check on the input data and if /// that fails returns a `TsicReadError::ParityCheckFailed`. fn new(raw_bits: u16) -> Result<Self, TsicReadError> { if Self::has_even_parity(raw_bits) { Ok(Self { raw_bits }) } else { Err(TsicReadError::ParityCheckFailed) } } /// Returns the actual data without the parity bit. fn value(&self) -> u16 { self.raw_bits >> 1 } /// Performs parity bit checking on the raw packet value. fn has_even_parity(raw: u16) -> bool { raw.count_ones() % 2 == 0 } }