onecable/

lib.rs

#![no_std]
//! # OneCable
//! `onecable` is an implementation of the 1-Wire protocol,
//! and is currently focussed of supporting the `DS18B20` temperature sensor.
//!
//! ## How to use?
//!
//! First, create a OneWire instance with [`OneWire::new`],
//! then you can discover the ROM codes of the connected devices with e.g. [`OneWire::search_rom_iter`].
//! If you have only one device connected to the OneWire bus, you can also use
//! [`OneWire::read_rom`] to read the ROM code of that device.
//!
//! Once you have a valid ROM code, you can convert it to a DS18B20 sensor instance with
//! [`ds18b20::DS18B20::try_from`].

pub mod crc;
pub mod ds18b20;
pub mod rom_code;
pub mod search_rom;
pub mod wirelock;

use crc::crc8_maxim;
use embedded_hal::{
    self,
    delay::DelayNs,
    digital::{InputPin, OutputPin},
};
use rom_code::RomCode;
use search_rom::OneWireRomIter;

/// Represents the OneWire bus.
///
/// Further information:
/// <https://www.analog.com/media/en/technical-documentation/data-sheets/DS18B20.pdf>
pub struct OneWire<'a, P: InputPin + OutputPin> {
    pin: &'a mut P,
}

impl<'a, P: InputPin + OutputPin> OneWire<'a, P> {
    /// pin needs to be an open drain pin
    pub fn new(pin: &'a mut P) -> Self {
        Self { pin }
    }

    /// Sends a RESET pulse and listens for a PRESENCE pulse.
    ///
    /// Retrurns `Ok(true)`, if a PRESENCE pulse is received, `Ok(false)` if not.
    ///
    /// `delay` must be able to accurately handle delays in the range of 1-480 us.
    pub fn initialize_bus(&mut self, delay: &mut impl DelayNs) -> Result<bool, P::Error> {
        self.pin.set_high()?;
        delay.delay_us(2);
        while self.pin.is_low()? {
            delay.delay_us(2);
        }

        self.pin.set_low()?;
        delay.delay_us(480);
        self.pin.set_high()?;

        // Devices wait 15-60 us and transmit 60-240 us.
        // So, in a window from 60 - 75 us after bus release the device signal should be stable.
        delay.delay_us(67);
        let is_present = self.pin.is_low()?;

        // overall device transmit window is 480 us wide
        delay.delay_us(480 - 67);
        Ok(is_present)
    }

    /// Writes a single bit to the OneWire bus.
    ///
    /// `delay` must be able to accurately handle delays in the range of 5-65 us.
    pub fn write_bit(&mut self, bit: bool, delay: &mut impl DelayNs) -> Result<(), P::Error> {
        match bit {
            true => {
                self.pin.set_low()?;
                delay.delay_us(10);
                self.pin.set_high()?;
                delay.delay_us(50);
            }
            false => {
                self.pin.set_low()?;
                delay.delay_us(65);
                self.pin.set_high()?;
            }
        }

        // recovery time
        delay.delay_us(5);

        Ok(())
    }

    /// Reads a single bit from the OneWire bus.
    ///
    /// `delay` must be able to accurately handle delays in the range of 3-53 us.
    pub fn read_bit(&mut self, delay: &mut impl DelayNs) -> Result<bool, P::Error> {
        // request bit
        self.pin.set_low()?;
        delay.delay_us(3);
        self.pin.set_high()?;
        delay.delay_us(10);

        // 0: device pulls bus low
        // 1: device leaves bus high
        let bit = self.pin.is_high()?;

        // 52 us wait for frame end + 1 us recovery time
        delay.delay_us(53);

        Ok(bit)
    }

    /// Writes a byte to the OneWire bus,
    /// least significant bit first.
    ///
    /// For requirements on `delay`, see [`OneWire::write_bit`].
    pub fn write_byte(&mut self, byte: u8, delay: &mut impl DelayNs) -> Result<(), P::Error> {
        let mut byte = byte;
        // least significant bit first
        for _ in 0..8 {
            let bit = byte & 1 == 1; // extract lowest bit of byte
            byte >>= 1;
            self.write_bit(bit, delay)?;
        }
        Ok(())
    }

    /// Reads a byte from the OneWire bus,
    /// least significant bit first.
    ///
    /// For requirements on `delay`, see [`OneWire::read_bit`].
    pub fn read_byte(&mut self, delay: &mut impl DelayNs) -> Result<u8, P::Error> {
        let mut byte = 0u8;
        // least significant bit first,
        // so push the bits at the front, and shift right
        for _ in 0..8 {
            byte >>= 1;

            let bit = self.read_bit(delay)?;

            // set highest bit of byte
            if bit {
                byte |= 0b10000000;
            };
        }
        Ok(byte)
    }

    /// Issues a `Read Rom` command to the OneWire bus.
    ///
    /// Only yields valid data, if exactly one other device is connected to the OneWire bus.
    /// Since all devices connected to the OneWire bus will respond, the data will be corrupt if multiple do so.
    pub fn read_rom(
        &mut self,
        delay: &mut impl DelayNs,
    ) -> Result<RomCode, OneWireError<P::Error>> {
        if !self.initialize_bus(delay)? {
            return Err(OneWireError::NoDevicePresent());
        }

        let read_rom_command = 0x33u8;
        self.write_byte(read_rom_command, delay)?;

        // most significant byte first
        let mut bytes = [0; 8];
        for byte in &mut bytes {
            *byte = self.read_byte(delay)?;
        }
        let crc = crc8_maxim(&bytes[0..7]);
        if crc != bytes[7] {
            Err(OneWireError::CrCMismatch {
                crc_received: bytes[7],
                crc_calculated: crc,
            })
        } else {
            Ok(RomCode { bytes })
        }
    }

    /// Issues a `Match Rom` command to the OneWire bus.
    pub fn match_rom(
        &mut self,
        rom_code: RomCode,
        delay: &mut impl DelayNs,
    ) -> Result<(), OneWireError<P::Error>> {
        if !self.initialize_bus(delay)? {
            return Err(OneWireError::NoDevicePresent());
        }

        let match_rom_command = 0x55u8;
        self.write_byte(match_rom_command, delay)?;

        // least significant byte first
        for byte in rom_code.bytes {
            self.write_byte(byte, delay)?;
        }
        Ok(())
    }

    /// Issues a `Skip Rom` command to the OneWire bus.
    pub fn skip_rom(&mut self, delay: &mut impl DelayNs) -> Result<(), OneWireError<P::Error>> {
        if !self.initialize_bus(delay)? {
            return Err(OneWireError::NoDevicePresent());
        }

        let match_rom_command = 0xCCu8;
        self.write_byte(match_rom_command, delay)?;
        Ok(())
    }

    /// The iterator performs a `Search Rom` procedure.
    pub fn search_rom_iter<'b, D: DelayNs>(
        &'b mut self,
        delay: &'b mut D,
    ) -> OneWireRomIter<'a, 'b, P, D, false> {
        OneWireRomIter::from_wire(self, delay)
    }

    /// The iterator performs an `Alarm Search` procedure.
    pub fn alarm_search_iter<'b, D: DelayNs>(
        &'b mut self,
        delay: &'b mut D,
    ) -> OneWireRomIter<'a, 'b, P, D, true> {
        OneWireRomIter::alarm_from_wire(self, delay)
    }
}

#[derive(Debug, thiserror::Error)]
pub enum FamilyCodeError {
    #[error("Expected to find family code {expected:X}, but found family code {received:X}.")]
    MismatchedFamilyCode { expected: u8, received: u8 },
}

#[derive(Debug, thiserror::Error)]
pub enum OneWireError<PinErr> {
    #[error("An error occourred on the OneWire pin.")]
    PinError(#[from] PinErr),
    #[error(
        "CRC={crc_received:X} of the data does not match the calculated CRC={crc_calculated:X}"
    )]
    CrCMismatch {
        crc_received: u8,
        crc_calculated: u8,
    },
    #[error("No device responded to the Reset pulse with a Presence pulse.")]
    NoDevicePresent(),
}