Forem: Nikolai Golub

Reading temperature sensor in Rust using Raspberry Pi GPIO

Nikolai Golub — Sun, 17 May 2020 19:20:00 +0000

Intro

While learning Rust one of the exercises I always wanted to try is GPIO and low-level device communication.Simple examples like configuring button handler or led blinking are not that exciting because they are not practical.Reading temperature and humidity, on the contrary, allows building something like a weather station or just simple graphs.While it will be much easier to use python with existing libraries. In my opinion, writing it in Rust assembles efficiency of C and readability and safety of Python.

Devices

I use the AM2302 sensor, which is a wired version of DHT22 sensor and Raspberry Pi 3 Model B+, which is on the picture above.

Connection

Utility pinout which is part of python-gpiozero package, allows to get an actual number of the pin for a particular Raspberry Pi model,here is part of the output for the Raspberry Pi 3 model:

   3V3 (1) (2) 5V
 GPIO2 (3) (4) 5V
 GPIO3 (5) (6) GND
 GPIO4 (7) (8) GPIO14
   GND (9) (10) GPIO15

The red wire goes to pin 2 5V. Most other examples use 3.3V pin, but I decided to use 5 to avoid low voltage issues.
Black wire goes to pin 9, ground. Any other ground can be used.
Yellow wire goest to pin 7, which refered as GPIO4, so 4 will be used in the code

Code

There are several options for working with GPIO interface in Rust:

I decided to use gpio-cdev package, as sysfs interface is going to be deprecated.

Prepare

First, adding a dependency to Cargo.toml:

[dependencies]
gpio-cdev = "0.2"

Gpio-cdev has pretty clear and simple documentation so we can have this function to get a line object.As documentation describes line: “Lines are offset within gpiochip0”

use gpio_cdev::{Chip, Line};

fn get_line(gpio_number: u32) -> Line {
    let mut chip = Chip::new("/dev/gpiochip0").unwrap();
    chip.get_line(gpio_number).unwrap()
}

gpio_number in my case is 4.

Requesting data

According to the sensor documentation to initialize data transfer from the device, it should be set the status to zero (pull down) for about 1 - 10 milliseconds.

use std::{thread, time};
use gpio_cdev::{Chip, LineRequestFlags, Line};

fn do_init(line: &Line) {
    let output = line.request(
        LineRequestFlags::OUTPUT,
        HIGH,
        "request-data").unwrap();
    output.set_value(0).unwrap();
    thread::sleep(time::Duration::from_millis(3));
}

Reading Data, Part 1

There are 2 options reading the data,

Pulling data manually using line request and .get_value() method
Subscribing to events from the line, using .events() method of the line

Let’s try first approach as it is straight forward.

In following example we will read state for changes during 10 seconds

let contact_time = time::Duration::from_secs(10);
let input = line.request(
    LineRequestFlags::INPUT,
    HIGH,
    "read-data").unwrap();

let mut last_state = input.get_value().unwrap();
let start = time::Instant::now();

while start.elapsed() < contact_time {
    let new_state = input.get_value().unwrap();
    if new_state != last_state {
        let timestamp = time::Instant::now();
        println!("Change of state {:?} => {:?}", last_state, new_state);
        last_state = new_state;
    }
}

But how to check if all these changes are valid data, or if initiliazing works properly?

I prefer to stop here, and start from other end: write decoding data part, and then get back to reading and check if data is correct.

Decoding data

Here is example from documentation on how data is repesented:

DATA=16 bits RH data+16 bits Temperaturedata+8 bits check-sum
Example: MCU has received 40 bits data from AM2302 as
         0000 0010 1000 1100 0000 0001 0101 1111 1110 1110
             16 bits RH data 16 bits T data check sum

         Here we convert 16 bits RH data from binary system to the decimal system,
         0000 0010 1000 1100 → 652
               Binary system Decimal system

         RH=652/10=65.2%RH

         Here we convert 16 bits T data from binary system to the decimal system,
         0000 0001 0101 1111 → 351
               Binary system Decimal system

         T=351/10=35.1°C

         When the highest bit of temperature is 1, 
         it means the temperature is below 0 degrees Celsius.

         Example: 1000 0000 0110 0101, T= minus 10.1°C
                       16 bits T data

         Sum = 0000 0010 + 1000 1100 + 0000 0001 + 0101 1111 = 1110 1110 

         Check-sum = the last 8 bits of Sum = 1110 1110

So let’s express it in Rust!

I define Reading struct that will hold actual temperature and humidity

#[derive(Debug, PartialEq)]
pub struct Reading {
    temperature: f32,
    humidity: f32,
}

Data we receive is not always correct, so errors will happen, this enum will represent it:

#[derive(Debug, PartialEq)]
pub enum CreationError {
    // Wrong number of input bites, should be 40
    WrongBitsCount,
    // Something wrong with conversion to bytes
    MalformedData,
    // Parity Bit Validation Failed
    ParityBitMismatch,
    // Value is outside of specification
    OutOfSpecValue,
}

And to build reading we will need to define a constructor, that will take vector of bytes and converts it to Reading.

It checks:

That there are only 40 bits
That vector contains only 1s and 0s
That checksum is correct
That actual values are valid by specification

It also does all the necessary conversions.

Note, that convert function that converts vector of 1s and 0s to integer is described in my another article

Also, specificaion does not mention it explicitly, but check sum is counted with overflow.

impl Reading {
    pub fn from_binary_vector(data: &[u8]) -> Result<Self, CreationError> {
        if data.len() != 40 {
            return Err(CreationError::WrongBitsCount);
        }

        let bytes: Result<Vec<u8>, ConversionError> = data.chunks(8)
            .map(|chunk| -> Result<u8, ConversionError> { convert(chunk) })
            .collect();

        let bytes = match bytes {
            Ok(this_bytes) => this_bytes,
            Err(_e) => return Err(CreationError::MalformedData),
        };

        let check_sum: u8 = bytes[..4].iter()
            .fold(0 as u8, |result, &value| result.overflowing_add(value).0);
        if check_sum != bytes[4] {
            return Err(CreationError::ParityBitMismatch);
        }

        let raw_humidity: u16 = (bytes[0] as u16) * 256 + bytes[1] as u16;
        let raw_temperature: i16 = if bytes[2] >= 128 {
            bytes[3] as i16 * -1
        } else {
            (bytes[2] as i16) * 256 + bytes[3] as i16
        };

        let humidity: f32 = raw_humidity as f32 / 10.0;
        let temperature: f32 = raw_temperature as f32 / 10.0;

        if temperature > 81.0 || temperature < -41.0 {
            return Err(CreationError::OutOfSpecValue);
        }
        if humidity < 0.0 || humidity > 99.9 {
            return Err(CreationError::OutOfSpecValue);
        }

        Ok(Reading { temperature, humidity })
    }
}

And it is always a good idea to write tests for it. Here I will only show couple of them, the rest is available in the repository

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn wrong_parity_bit() {
        let result = Reading::from_binary_vector(
            &vec![
                0, 0, 0, 0, 0, 0, 1, 0, // humidity high
                1, 0, 0, 1, 0, 0, 1, 0, // humidity low
                0, 0, 0, 0, 0, 0, 0, 1, // temperature high
                0, 0, 0, 0, 1, 1, 0, 1, // temperature low
                1, 0, 1, 1, 0, 0, 1, 0, // parity
            ]
        );
        assert_eq!(result, Err(CreationError::ParityBitMismatch));
    }

    #[test]
    fn correct_reading() {
        let result = Reading::from_binary_vector(
            &vec![
                0, 0, 0, 0, 0, 0, 1, 0, // humidity high
                1, 0, 0, 1, 0, 0, 1, 0, // humidity low
                0, 0, 0, 0, 0, 0, 0, 1, // temperature high
                0, 0, 0, 0, 1, 1, 0, 1, // temperature low
                1, 0, 1, 0, 0, 0, 1, 0, // parity
            ]
        );

        let expected_reading = Reading {
            temperature: 26.9,
            humidity: 65.8,
        };

        assert_eq!(result, Ok(expected_reading));
    }

}

Having all this allows to get back to reading actual data and check if it is correct.

Reading Data, Part 2

How do I convert all these state changes to a vector of bits?

According to documentation, actual values are represented by the amount of time signal was in 1 state, where

0 for 26-28 microseconds
1 for 70 microseconds

But another document by aosong.com I’ve found shows this table:

Parameter	Min	Typical	Max	Unit
Signal “0” high time	22	26	30	μS
Signal “1” high time	68	70	75	μS

So considering error in measurements, I will take 35 milliseconds as the cutoff between 1 and 0.Also, I want to separate reading data and parsing it, so no CPU cycles will be spent during receiving on other than reading data from device.

“Raw data” will be represented with Event structure, which will have timestamp and type:

#[derive(Debug, PartialEq)]
enum EvenType {
    RisingEdge,
    FallingEdge,
}

#[derive(Debug)]
struct Event {
    timestamp: time::Instant,
    event_type: EvenType,
}

impl Event {
    pub fn new(timestamp: time::Instant, event_type: EvenType) -> Self {
        Event { timestamp, event_type }
    }
}

And to convert vector of events to vector 1 or 0s pretty handy .windows iterator method will be used

fn events_to_data(events: &[Event]) -> Vec<u8> {
    events
        .windows(2)
        .map(|pair| {
            let prev = pair.get(0).unwrap();
            let next = pair.get(1).unwrap();
            match next.event_type {
                EvenType::FallingEdge => Some(next.timestamp - prev.timestamp),
                EvenType::RisingEdge => None,
            }
        })
        .filter(|&d| d.is_some())
        .map(|elapsed| {
            if elapsed.unwrap().as_micros() > 35 { 1 } else { 0 }
        }).collect()
}

Read events function should be just record timestamp of the changes and change type:

fn read_events(line: &Line, events: &mut Vec<Event>, contact_time: time::Duration) {
    let input = line.request(
        LineRequestFlags::INPUT,
        HIGH,
        "read-data").unwrap();

    let mut last_state = input.get_value().unwrap();
    let start = time::Instant::now();

    while start.elapsed() < contact_time {
        let new_state = input.get_value().unwrap();
        if new_state != last_state {
            let timestamp = time::Instant::now();
            let event_type = if last_state == LOW && new_state == HIGH {
                EvenType::RisingEdge
            } else {
                EvenType::FallingEdge
            };
            events.push(Event::new(timestamp, event_type));
            if events.len() >= 83 {
                break;
            }
            last_state = new_state;
        }
    }
}

Events vector is created outside of this function, because request to device is done before, spending time creating new vector can lead to loss of events.

Combining it all together and testing

in main.rs I will declare 2 function, try_read, which will get bits we were able to pull from the device and check they can be converted to the data.:

fn try_read(gpio_number: u32) -> Option<Reading> {
    let mut final_result = None;
    let all_data = push_pull(gpio_number);
    if all_data.len() < 40 {
        println!("Saad, read not enough data");
        return final_result;
    }
    for data in all_data.windows(40) {
        let result = Reading::from_binary_vector(&data);
        match result {
            Ok(reading) => {
                final_result = Some(reading);
                break;
            }
            Err(e) => {
                println!("Error: {:?}", e)
            }
        }
    }
    final_result
}

And main function simply tries to read every 5 seconds:

fn main() {
    let gpio_number = 4; // GPIO4 (7)
    let sleep_time = time::Duration::from_secs(5);
    for _ in 1..30 {
        println!("Sleeping for another {:?}, to be sure that device is ready", sleep_time);
        thread::sleep(sleep_time);
        match try_read(gpio_number) {
            Some(reading) => println!("Reading: {:?}", reading),
            None => println!("Unable to get the data"),
        }
    }
}

Output will look like this:

   Compiling rust_gpio v0.1.0 (/home/pi/workspace/rust_gpio)
    Finished dev [unoptimized + debuginfo] target(s) in 4.02s
     Running `target/debug/rust_gpio`
Sleeping for another 5s, to be sure that device is ready
Error: ParityBitMismatch
Error: ParityBitMismatch
Unable to get the data
Sleeping for another 5s, to be sure that device is ready
Error: ParityBitMismatch
Reading: Reading { temperature: 23.2, humidity: 37.7 }
Sleeping for another 5s, to be sure that device is ready
Error: OutOfSpecValue
Reading: Reading { temperature: 23.2, humidity: 68.2 }
Sleeping for another 5s, to be sure that device is ready
Error: ParityBitMismatch

As you might see, it is not always to possible to read the data, and often first attemp is ParityBitMisMatch

Note on a different approach

Pulling doesn’t look like the most performant way of reading data, and subscribing to events using .events() method suppose to be more efficient, but I was unable to get enough transitions in the callback. I haven’t investigated, why this is happening.

Conclusion

Making binary data more readable simplifies experimentation a lot!

Only tests can make “some rust code” to become “rust code you trust”.

Couple improvement can be done, such as:

Skipping 1st bit if there are 41 bits was received, as it is signal bit
Allocating space for a vector of events upfront
Making pin to be a command-line argument
More extensive testing

The full example is available in GitHub Repository citizen-stig/gpio-am2302-rs

Converting bits to integers in Rust using generics

Nikolai Golub — Sat, 04 Apr 2020 19:26:00 +0000

Let’s imagine there’s input from some device, that produces only zeros and ones and it needed to be converted into actual integers, something like

let bits: Vec<u8> = vec![0, 0, 0, 0, 0, 1, 0, 1];
let result: u8 = convert(&bits);
assert_eq!(result, 5);

In this article, I will show how Rust functions can be generalized using generics and which problem I faced.

Naive solution

Here’s my first and naive implementation:

fn convert(bits: &[u8]) -> u8 {
    let mut result: u8 = 0;
    bits.iter().for_each(|&bit| {
        result <<= 1;
        result ^= bit;
    });
    result
}

No magic, doing bit shift, and then XORing result with each bit. If it is 1 it will be added to result, if it is zero, zero remains in the rightmost position.

But there’s room for improvement. fold function is more idiomatic:

fn convert(bits: &[u8]) -> u8 {
    bits.iter()
        .fold(0, |result, &bit| {
            (result << 1) ^ bit
        })
}

Generic Approach

The last solution is quite good, but it only produces an output of type u8. What if we want to have u32, or i64. Rust has support of Generic Data Types for cases like that, let’s try!

We will need PartialEq, BitXor, Shl and From<bool> traits to define behavior inside convert function:

use std::cmp::PartialEq;
use std::ops::Shl;
use std::ops::BitXor;

fn convert<T: PartialEq + From<bool> + BitXor + Shl>(bits: &[T]) -> T {
    let zero = T::from(false);
    let one = T::from(true);
    bits.iter()
        .filter(|&&bit| bit == zero || bit == one)
        .fold(zero, |result, bit| (result << one) ^ bit)
}

But this implementation gives this error during compilation:

10 | .fold(zero, |result, bit| (result << one) ^ bit)
   | --------------- ^ --- &T
   | |
   | <T as std::ops::Shl>::Output
   |
   = note: an implementation of `std::ops::BitXor` might be 
                            missing for `<T as std::ops::Shl>::Output`

Hm, this doesn’t seem right. According to trait declaration, it has Output defined as Associated type:

pub trait Shl<Rhs = Self> {
    type Output;

    fn shl(self, rhs: Rhs) -> Self::Output;
}

Based on documentation BitXor has an implementation for bool, which doesn’t have implementation for output of << operator.

Associated type is syntactic sugar and thankfully, Rust allows putting constraints on generic function implementation:

use std::cmp::PartialEq;
use std::ops::BitXor;
use std::ops::Shl;

fn convert<T: PartialEq + From<bool> + BitXor<Output = T> + Shl<Output = T> + Clone>(
    bits: &[T],
) -> T {
    let zero = T::from(false);
    let one = T::from(true);
    bits.iter()
        .filter(|&bit| bit == &zero.clone() || bit == &one.clone())
        .fold(zero.clone(), |result, bit| {
            (result << one.clone()) ^ bit.clone()
        })
}

It also has a couple of other fixes, but generally, this is a working solution for all integer types.

Improvements

What if I want to add the following to my function:

Check if the input vector is larger than the target integer
Check if the vector has only ones and zeros
Reduce memory footprint, by changing input vector always be u8, and the return type will be derived from caller definition.

The first thing we need to do, is to change output type from plain T to Result<T, ConversionError> where ConversionError is an enum, that holds all error types we have:

#[derive(Debug)]
pub enum ConversionError {
    Overflow,
    NonBinaryInput,
}

To check the size of a generic type we will use std::mem::size_of like that:

if bits.len() > (std::mem::size_of::<T>() * 8) {
    return Err(ConversionError::Overflow);
}

Changing the input vector to always be u8 as the smallest integer is a questionable change because it forces always explicitly declare a return type, but I believe it is a fair deal for reducing memory size.

This is how it should be called now:

let bits: Vec<u8> = vec![0, 0, 0, 0, 0, 1, 0, 1];
let result: Result<u32, ConversionError> = convert(&bits);
assert_eq!(result.unwrap(), 5);

Function signature will change mainly in From<boolean> to From<u8>:

pub fn convert<T: PartialEq + From<u8> + BitXor<Output=T> + Shl<Output=T> + Clone>(
    bits: &[u8],
) -> Result<T, ConversionError> {

Checking that input has only zeros and ones is optional, but can be done with simple filtering and counting:

if bits.iter()
    .filter(|&&bit| bit != 0 && bit != 1).count() > 0 {
    return Err(ConversionError::NonBinaryInput);
}

The final solution with all latest changes:

use std::cmp::PartialEq;
use std::ops::BitXor;
use std::ops::Shl;

#[derive(Debug)]
pub enum ConversionError {
    Overflow,
    NonBinaryInput,
}

pub fn convert<T: PartialEq + From<u8> + BitXor<Output=T> + Shl<Output=T> + Clone>(
    bits: &[u8],
) -> Result<T, ConversionError> {
    if bits.len() > (std::mem::size_of::<T>() * 8) {
        return Err(ConversionError::Overflow);
    }
    if bits.iter()
        .filter(|&&bit| bit != 0 && bit != 1).count() > 0 {
        return Err(ConversionError::NonBinaryInput);
    }

    Ok(bits.iter()
        .fold(T::from(0), |result, &bit| {
            (result << T::from(1)) ^ T::from(bit)
        }))
}

5 reasons to mentor on exercism.io

Nikolai Golub — Tue, 24 Sep 2019 20:37:01 +0000

What is exercism.io

About page of exercism.io says:

Exercism is an online platform designed to help you improve your coding skills through practice and mentorship.

But what exercism really is and how it's different from dozens of other coding practicing platforms?

For me, as a learner, it's the only platform I've seen so far where you can learn idiomatic use of any language. If you're a python developer and have seen code like this, you will get the idea:

my_list = ['dog', 'cat', 'hamster']
for i in range(len(my_list)):
    animal = my_list[i]
    print(animal)

And if you're not familiar with python, above code is one of the examples of C-style programming in python, more idiomatic version:

my_list = ['dog', 'cat', 'hamster']
for animal in my_list:

    print(animal)

It's worthwhile to use language as it supposed to be used. And Exercism achieves that by building a community of mentors who provide you feedback on how readable, performant, and idiomatic your solution. It is not about making code passing the tests.

So basically Exercism is like Archlinux among coding learning platforms.

And I didn't even mention that it's not web-based, they have CLI, so you can use your favorite IDE or vim.

It's all about learning, but why mentoring there?

Reasons to mentor

1. Read more code from learners

Why do you need to read other's people code? Because it's one of the fastest ways to learn programming in general. Other people are different, and you can absorb their point of view, their mistakes, their ideas. It might be overwhelming to jump into Linux kernel sources, so better to start small.

As a mentor on Exercism, you can compare multiple solutions of the same problem, see what mistakes people do, what style they use, how it fits particular language.

That's how you become fluent.

2. Practice your communication styles

So programmers not only read and write code, but they also communicate with other people. That's actually one of the essential parts of the job, in my opinion.
Good ideas can die because they weren't communicated properly. Bugs get introduced, people call tech industry toxic, a lot of things happen because developers don't master skills in human language.

It's an excellent opportunity to grow, where you can learn and practice, how to express your thoughts to other developers. You will get feedback from them, there's even slack for mentors. This is how you can stand out from the crowd. I'm not saying you'll become 10X developer, but you'll become better

3. Sandboxed discussions

If you like to speak about programming in a bar or around a coffee machine, but not everyone shares your passion, that's not a problem.

Most of the solution discussions on Exercism are about style, convention, micro-optimization, and readability. You don't have deadlines, business priorities, etc. Just enjoy pure programming.

4. Make the world a better place

You take responsibility for how many good developers there will be in the world.
It's simple like that:

More good developers => better software => less bugs and stress.

Who knows, maybe one of the students you help will create another open-source framework or project, that will generate thousands of workplaces.

5. Pay it forward

How often someone helped you on StackOverflow, Github or this random forum? You can do this too, and it won't be that hard as diving into a big open-source project or compete on StackOverflow.
And Exercism is the right place to start giving back to the community.

Someone might say

Nah, there's enough mentors for Python/Javascript/Java, my help is not needed

But that's not true, and it's not even about other mentors. It's about you caring about your craft.

What's next?

Signup to become a mentor and make it happen! Enjoy and spread the word.

P.s. Languages selection on the platform is impressive.