Alone on a Mountaintop

Schedule Software Tasks With RTFM

2020-06-13T22:01:42+00:00

This week, we will look at the task scheduling feature of the RTFM framework. This is a redo of the last project that reads when new data is available on USART and sends the accumulated data through USART every second.

Here are three things we implement:

initialize USART TX, RX, and producer/consumer for a buffer and store them for later use.
When new data arrives on USART, enter an interrupt context to read the data and write it to the buffer.
Every second, see if there are any data available in the buffer and send them through USART.

Instead of using a Timer to trigger an interrupt every second, we will schedule a software task this time.

Hardware

Nucleo-F429ZI

Crates

Code

Full code is available on GitHub

Implementation

1 and 2 in the list above are the same as the last project. In this post, I will only focus on 3, how to schedule software tasks.

This shows an overview of the application.

// import crates, declare buffer queue, etc.

const PERIOD: u32 = 16_000_000;

#[rtfm::app(device = hal::stm32, peripherals = true, monotonic = rtfm::cyccnt::CYCCNT)]
const APP: () = {
    struct Resources {
        cons: Consumer<'static, U1024>,
        prod: Producer<'static, U1024>,
        tx: hal::serial::Tx<USART3>,
        rx: hal::serial::Rx<USART3>,
    }

    #[init(schedule = [tx_write])]
    fn init(cx: init::Context) -> init::LateResources {
        // Schedule a tx_write task
        // Split bbqueue Producer and Consumer
        // Set up USART, enable interrupt
        // Initialization of late resources
    }

    #[task(binds = USART3, resources = [prod, rx])]
    fn usart3(cx: usart3::Context) {
        // receive data from USART
        // write to the queue
    }

    #[task(schedule = [tx_write], resources = [cons, tx])]
    fn tx_write(cx: tx_write::Context) {
        // read from the queue and write to USART
        // reschedule tx_write
    }

    // This is required for the software task fn tx_write()
    // This can be any interrupt not used by the hardware
    extern "C" {
        fn USART1();
    }
};

There are two tasks here: usart3 and tx_write.

usart3 is a hardware task. We enable RX interrupt in init.

tx_write is the software task we want to focus on.

Schedule a task to run sometime in the future

To schedule a task, we use a Monotonic timer.

Let’s look at the #[app] attribute where we specify the microcontroller’s 32-bit cycle counter as our monotonic timer.

#[rtfm::app(device = hal::stm32, 
	peripherals = true, 
	monotonic = rtfm::cyccnt::CYCCNT)]

Since we set the system clock to 16MHz, clocking 16,000,000 times equals to 1 second. We declare a constant like this.

const PERIOD: u32 = 16_000_000;

Just like we specify which resources to use in the context attribute, we need to pass tasks to the schedule arguments of the context attribute.

Let’s look at init and tx_write where we schedule tasks. See we have schedule argument in the context attribute. We pass our tx_write as an argument.

    #[init(schedule = [tx_write])]
    fn init(cx: init::Context) -> init::LateResources {
	    cx.schedule
	        .tx_write(cx.start + PERIOD.cycles())
	        .unwrap();
		// ...
    }

    #[task(schedule = [tx_write], resources = [cons, tx])]
    fn tx_write(cx: tx_write::Context) {
		cx.schedule
	        .tx_write(cx.scheduled + PERIOD.cycles())
	        .unwrap();
        // ...
    }

In the tasks, we schedule a task by calling Context’s schedule API. In init(), we schedule tx_write to run 16,000,000 cycles (= 1 second) in the future.

cx.schedule.tx_write(cx.start + PERIOD.cycles()).unwrap();

cx.start returns start time of the system, which should be 0. The line above schedules a task to run after the specified cycles (PERIOD: u32 = 16_000_000).

In tx_write, we write to USART and reschedule a task so that it is called again after the specified clock cycles.

cx.schedule.tx_write(cx.scheduled + PERIOD.cycles()).unwrap();

We can access the previously scheduled time through cx.scheduled. We add 16,000,000 cycles to the whatever scheduled time.

Nice. We can now fire a task every second using RTFM framework.

NVIC as a dispatcher

By the way, you may wonder why we have these lines.

    extern "C" {
        fn USART1();
    }

My understanding is that RTFM uses the NVIC to handle scheduling. We just need to specify enough unused extern interrupts so that RTFM can dispatch software tasks.

Since we only have one software task for this project, one is enough here. It doesn’t have to be fn USART1(). It can be TIM2 or whatever interrupt not used by the hardware. If we have two software tasks with different priorities, we need two extern interrupts.

Serial Communication with RTFM

2020-05-29T15:05:48+00:00

Our experiment with RTFM continues. This week’s project involves USART read/write and Timer interrupt. We will read when new data is available on USART, and send the accumulated data through USART every second.

Hardware

Nucleo-F429ZI

Crates

Code

Full code is available on GitHub

Implementation

Here are three things we need to implement:

initialize USART TX, RX, Timer, and producer/consumer for a global shared buffer and store them for later use.
When new data arrives on USART, enter an interrupt context to read the data and write it to the buffer.
Every second, retrieve available data from the buffer and send them through USART.

Here is the pseudo code:

#[rtfm::app(device = hal::stm32, peripherals = true)]
const APP: () = {
    struct Resources {
        cons: Consumer<'static, U1024>,
        prod: Producer<'static, U1024>,
        tx: hal::serial::Tx<USART3>,
        rx: hal::serial::Rx<USART3>,
        timer: Timer<stm32::TIM2>,
    }

    #[init]
    fn init(cx: init::Context) -> init::LateResources {
        // initialization of resources
		// ...

        init::LateResources {
            cons,
            prod,
            tx,
            rx,
            timer,
        }
    }

    // UART interrupt
    #[task(binds = USART3, resources = [prod, rx])]
    fn usart3(cx: usart3::Context) {
		// read from the RX buffer and write to the queue
    }

    // Timer interrupt 
    #[task(binds = TIM2, resources = [timer, cons, tx])]
    fn tim2(cx: tim2::Context) {
        // read the currently available data from the queue and write to the TX buffer
    }
};

BBQueue: A SPSC, lockless, no_std, thread safe, queue

The challenge is how to write and read the shared buffer. Writing to the buffer occurs in USART ISR contexts and reading from it occurs in Timer ISR contexts. For this project, we use BBQueue, First-In-First-Out queue, to safely perform write/read transactions.

First, we create a large enough buffer. Here is how we create a buffer with 1024 elements.

static BB: BBBuffer<U1024> = BBBuffer(ConstBBBuffer::new());

To access the buffer, we use Producer and Consumer. In init(), we split BBQueue Producer and Consumer and store them in our Resources. We will later use prod (for writing) in the USART ISR and cons (for reading) in the Timer ISR.

#[init]
fn init(cx: init::Context) -> init::LateResources {
	// Set up USART, Timer
	// ...

    // Split bbqueue Producer and Consumer
    let (prod, cons) = BB.try_split().unwrap();

    // Initialization of late resources
    init::LateResources {
        cons,
        prod,
        tx,
        rx,
        timer,
    }
}

USART and Timer Resources

The initialization of USART resources is straightforward. Crate a Serial instance with pins and clocks. When we call listen(SerialEvent::Rxne), our Serial starts listening on RX and triggers an interrupt when a new data arrives. Finally, we split TX and RX so that we can use them in separate contexts.

let gpioc = cx.device.GPIOC.split();
let tx = gpioc.pc10.into_alternate_af7();
let rx = gpioc.pc11.into_alternate_af7();
let mut serial = Serial::usart3(
    cx.device.USART3,
    (tx, rx),
    Config::default().baudrate(9_600.bps()),
    clocks,
)
.unwrap();
// Start listening on RX
serial.listen(SerialEvent::Rxne);
// Split TX and RX
let (tx, rx) = serial.split();

We also initialize a Timer in init() and let it start running.

let mut timer = Timer::tim2(cx.device.TIM2, 1.hz(), clocks);
timer.listen(TimerEvent::TimeOut);

After initializing all the resources, we store them as LateResources .

init::LateResources {
    cons,
    prod,
    tx,
    rx,
    timer,
}

Interrupt Handlers

Now, let’s look at the interrupt handlers. USART3 interrupt is handled like this.

#[task(binds = USART3, resources = [prod, rx])]
fn usart3(cx: usart3::Context) {
    match block!(cx.resources.rx.read()) {
        Ok(byte) => {
            if let Ok(mut wgr) = cx.resources.prod.grant_exact(1) {
                wgr[0] = byte;
                wgr.commit(1);
            }
        }
        Err(error) => {
            iprintln!(itm(), "[RX] Err: {:?}", error);
        }
    }
}

binds = USART3 establishes a link to USART3 hardware interrupt. In this ISR context, we use rx: hal::serial::Rx to read a new byte and write to the buffer using prod: bbqueue::Producer.

prod.grant_exact(1) request space for one byte. We write the value of the received byte to it and call commit. Committing returns the space for later use. Next time around, we request another grant and write a new value.

While we accumulate incoming data and put them in the buffer in USART interrupts, we read from the buffer and send the data out through USART’s TX in Timer interrupts.

Here is the TIM2 interrupt handler.

#[task(binds = TIM2, resources = [timer, cons, tx])]
fn tim2(cx: tim2::Context) {
    cx.resources.timer.clear_interrupt(TimerEvent::TimeOut);
    let rgr = match cx.resources.cons.read() {
        Ok(it) => it,
        _ => return,
    };
    
    rgr.buf()
        .iter()
        .for_each(|&byte| block!(cx.resources.tx.write(byte)).unwrap());

    // Release the space for later writes
    let len = rgr.len();
    rgr.release(len);
}

We use cons: bbqueue::Consumer to read the buffer. When the buffer is empty, cons.read() returns Err. If there are bytes to read, we access the data slice by calling buf(). The size of the slice could be anywhere between 1 byte and the size of the buffer. Whatever the size is, it is guaranteed to be contiguous.

We then iterate through it and write to TX. When we are done with writing, we release the space for later writes.

Rust’s Real Time For the Masses (RTFM): Between bare metal and Real Time OS

2020-05-22T23:45:41+00:00

In this post, I will talk about my first experiment with Real Time For the Masses (RTFM) Framework. My understanding is that RTFM finds itself between bare metal and Real Time OS. Bare metal’s small footprint is great for a resource-constrained platform. But managing resources and tasks can be very difficult. Real Time OS provides rich features. However, it comes with so much overhead. RTFM provides an ability to easily schedule tasks and guarantees safe access to shared resources without much runtime overhead.

Here are RTFM’s features listed in the doc.

Tasks as the unit of concurrency. Tasks can be event triggered (fired in response to asynchronous stimuli) or spawned by the application on demand.

Message passing between tasks. Specifically, messages can be passed to software tasks at spawn time.

A timer queue. Software tasks can be scheduled to run at some time in the future. This feature can be used to implement periodic tasks.

Support for prioritization of tasks and, thus, preemptive multitasking.

Efficient and data race free memory sharing through fine grained *priority based* critical sections.

Deadlock free execution guaranteed at compile time. This is an stronger guarantee than what’s provided by the standard Mutex abstraction.

Minimal scheduling overhead. The task scheduler has minimal software footprint; the hardware does the bulk of the scheduling.

Highly efficient memory usage: All the tasks share a single call stack and there’s no hard dependency on a dynamic memory allocator.

Timer interrupt with RTFM

This week’s program toggles an LED when triggered by timer interrupts.

Hardware

Nucleo-F429ZI

Crates

Code

Full code is available on GitHub

Implementation

This experiment is a redo of my timer interrupt experiment from a few weeks ago. Let’s look at how I did it without RTFM.

Without RTFM

static LED: Mutex<RefCell<Option<PB7<Output<PushPull>>>>> = Mutex::new(RefCell::new(None));
static TIMER_TIM2: Mutex<RefCell<Option<Timer<stm32::TIM2>>>> = Mutex::new(RefCell::new(None));

#[entry]
fn main() -> ! {
    let dp = stm32::Peripherals::take().unwrap();
    let rcc = dp.RCC.constrain();
    let clocks = rcc.cfgr.sysclk(48.mhz()).freeze();

    // Set up the LED
    let gpiob = dp.GPIOB.split();
    let led = gpiob.pb7.into_push_pull_output();

    // Set up the timer
    let mut timer = Timer::tim2(dp.TIM2, 5.hz(), clocks);
    timer.listen(Event::TimeOut);
	
    // Move shared resources to Mutex
    free(|cs| {
        TIMER_TIM2.borrow(cs).replace(Some(timer));
        LED.borrow(cs).replace(Some(led));
    });

    // Enable interrupt
    stm32::NVIC::unpend(stm32::Interrupt::TIM2);
    unsafe {
        stm32::NVIC::unmask(stm32::Interrupt::TIM2);
    }

    loop {}
}

#[interrupt]
fn TIM2() {
    free(|cs| {
        if let Some(ref mut tim2) = TIMER_TIM2.borrow(cs).borrow_mut().deref_mut() {
            tim2.clear_interrupt(Event::TimeOut);
        }
        if let Some(ref mut led) = LED.borrow(cs).borrow_mut().deref_mut() {
            led.toggle().unwrap();
        }
    });
}

The application does these:

use Mutex for shared resources that can be accessed from user and ISR contexts
enable TIM2 interrupt with NVIC
handle interrupt requests in #[interrupt] and toggle the LED

Now, let’s do the same with RTFM. Implementation with RTFM looks like this.

With RTFM

#[rtfm::app(device = hal::stm32, peripherals = true)]
const APP: () = {
    struct Resources {
        led: PB7<Output<PushPull>>,
        timer: Timer<stm32::TIM2>,
    }

    #[init]
    fn init(cx: init::Context) -> init::LateResources {
        let rcc = cx.device.RCC.constrain();
        let clocks = rcc.cfgr.freeze();

        // Set up the LED
        let gpiob = cx.device.GPIOB.split();
        let led = gpiob.pb7.into_push_pull_output();

        // Set up the timer
        let mut timer = Timer::tim2(cx.device.TIM2, 5.hz(), clocks);
        timer.listen(Event::TimeOut);

        // Initialization of late resources
        init::LateResources { led, timer }
    }

    #[task(binds = TIM2, resources = [timer, led])]
    fn tim2(cx: tim2::Context) {
        cx.resources.timer.clear_interrupt(Event::TimeOut);
        cx.resources.led.toggle().unwrap();
    }
};

This looks very different from what we have seen so far. To start, there is no #[entry] attribute. This may be confusing. We are supposed to initialize resources, enable interrupts, and infinitely loop in main like this.

#[entry]
fn main() -> ! {
	// configure pins, set up interrupt, wrap shared resouces with Mutex, etc.
    loop {}
}

Also, we can’t find NVIC anywhere either. Below is how we normally enable a timer interrupt without RTFM.

stm32::NVIC::unpend(Interrupt::TIM2);
unsafe {
    stm32::NVIC::unmask(Interrupt::TIM2);
}

So, where are our #[entry] and functions to enable interrupts?

RTFM framework uses macros. When we use attributes like #[init] and #[task], they expand and generate main and all that.

Code generation happens in the background and we don’t need to see the expanded code. We can just build an app and flash it to a device. But I think it is a good idea to see what exactly RTFM is doing first. At least for me, seeing the expanded code helped me understand what was going on.

Expanded Code

#[allow(non_snake_case)]
fn init(cx: init::Context) -> init::LateResources {
    let rcc = cx.device.RCC.constrain();
    let clocks = rcc.cfgr.freeze();
    let gpiob = cx.device.GPIOB.split();
    let led = gpiob.pb7.into_push_pull_output();
    let mut timer = Timer::tim2(cx.device.TIM2, 5.hz(), clocks);
    timer.listen(Event::TimeOut);
    init::LateResources { led, timer }
}
#[allow(non_snake_case)]
fn tim2(cx: tim2::Context) {
    use rtfm::Mutex as _;
    cx.resources.timer.clear_interrupt(Event::TimeOut);
    cx.resources.led.toggle().unwrap();
}
#[doc = r" Resources initialized at runtime"]
#[allow(non_snake_case)]
pub struct initLateResources {
    pub led: PB7<Output<PushPull>>,
    pub timer: Timer<stm32::TIM2>,
}
#[allow(non_snake_case)]
#[doc = "Initialization function"]
pub mod init {
    #[doc(inline)]
    pub use super::initLateResources as LateResources;
    #[doc = r" Execution context"]
    pub struct Context {
        #[doc = r" Core (Cortex-M) peripherals"]
        pub core: rtfm::export::Peripherals,
        #[doc = r" Device peripherals"]
        pub device: hal::stm32::Peripherals,
    }
    impl Context {
        #[inline(always)]
        pub unsafe fn new(core: rtfm::export::Peripherals) -> Self {
            Context {
                device: hal::stm32::Peripherals::steal(),
                core,
            }
        }
    }
}
#[allow(non_snake_case)]
#[doc = "Resources `tim2` has access to"]
pub struct tim2Resources<'a> {
    pub timer: &'a mut Timer<stm32::TIM2>,
    pub led: &'a mut PB7<Output<PushPull>>,
}
#[allow(non_snake_case)]
#[doc = "Hardware task"]
pub mod tim2 {
    #[doc(inline)]
    pub use super::tim2Resources as Resources;
    #[doc = r" Execution context"]
    pub struct Context<'a> {
        #[doc = r" Resources this task has access to"]
        pub resources: Resources<'a>,
    }
    impl<'a> Context<'a> {
        #[inline(always)]
        pub unsafe fn new(priority: &'a rtfm::export::Priority) -> Self {
            Context {
                resources: Resources::new(priority),
            }
        }
    }
}
#[doc = r" Implementation details"]
const APP: () = {
    #[doc = r" Always include the device crate which contains the vector table"]
    use hal::stm32 as _;
    #[cfg(core = "1")]
    compile_error!("specified 1 core but tried to compile for more than 1 core");
    #[allow(non_upper_case_globals)]
    #[link_section = ".uninit.rtfm0"]
    static mut timer: core::mem::MaybeUninit<Timer<stm32::TIM2>> = core::mem::MaybeUninit::uninit();
    #[allow(non_upper_case_globals)]
    #[link_section = ".uninit.rtfm1"]
    static mut led: core::mem::MaybeUninit<PB7<Output<PushPull>>> =
        core::mem::MaybeUninit::uninit();
    #[allow(non_snake_case)]
    #[no_mangle]
    unsafe fn TIM2() {
        const PRIORITY: u8 = 1u8;
        rtfm::export::run(PRIORITY, || {
            crate::tim2(tim2::Context::new(&rtfm::export::Priority::new(PRIORITY)))
        });
    }
    impl<'a> tim2Resources<'a> {
        #[inline(always)]
        unsafe fn new(priority: &'a rtfm::export::Priority) -> Self {
            tim2Resources {
                timer: &mut *timer.as_mut_ptr(),
                led: &mut *led.as_mut_ptr(),
            }
        }
    }
    #[no_mangle]
    unsafe extern "C" fn main() -> ! {
        rtfm::export::assert_send::<PB7<Output<PushPull>>>();
        rtfm::export::assert_send::<Timer<stm32::TIM2>>();
        rtfm::export::interrupt::disable();
        let mut core: rtfm::export::Peripherals = core::mem::transmute(());
        let _ = [(); ((1 << hal::stm32::NVIC_PRIO_BITS) - 1u8 as usize)];
        core.NVIC.set_priority(
            hal::stm32::Interrupt::TIM2,
            rtfm::export::logical2hw(1u8, hal::stm32::NVIC_PRIO_BITS),
        );
        rtfm::export::NVIC::unmask(hal::stm32::Interrupt::TIM2);
        core.SCB.scr.modify(|r| r | 1 << 1);
        let late = init(init::Context::new(core.into()));
        led.as_mut_ptr().write(late.led);
        timer.as_mut_ptr().write(late.timer);
        rtfm::export::interrupt::enable();
        loop {
            rtfm::export::wfi()
        }
    }
};

I find it very interesting to read the expanded code line by line. I can see fn main() at the bottom of the expanded code. In main, interrupt is enabled with NVIC and it infinitely waits for interrupts.

Although I don’t understand everything, it seems to me that resources are nicely managed with mod. I guess RTFM makes it a bit easier to handle resources and tasks.

Attributes

This is how our RTFM application is constructed.

#[rtfm::app(device = hal::stm32, peripherals = true)]
const APP: () = {

    struct Resources {
        led: PB7<Output<PushPull>>,
        timer: Timer<stm32::TIM2>,
    }

    #[init]
    fn (cx: init::Context) -> init::LateResources  {
        // omitted
    }
	
    // not used for this week's experiment
    // #[idle]
    // fn idle(c: idle::Context) -> ! {}

    #[task(binds = TIM2, resources = [timer, led])]
    fn tim2(c: tim2::Context) {
        // omitted
    }
};

Let’s look at the four attributes: app, init, idle and task.

1.`app`

All RTFM applications start with app.

#[rtfm::app(device = hal::stm32, peripherals = true)]
const App(): = {
    //
}

device argument is mandatory. We want to specify a path to our PAC crate here. In my case, it is stm32f4xx-hal’s stm32.

periperals = true makes it possible to access PAC’s core and device modules. For example, let rcc = cx.device.RCC.constrain();

2. `init`

app expects initialization functions in #[init]. This is the first thing that runs in an RTFM application. Interrupts are always disabled in this. We initialize resources in here.

3. `idle`

We don’t use this for this week’s experiment. But when we have this task, it runs after init with interrupt enabled.

4. `task`

#[task] attribute makes it possible to declare interrupt handler. Use binds to attach a handler to a specific interrupt.

#[task(binds = UART0)]
fn uart0(_: uart0::Context) {
    //
}

It is possible to set priority using priority argument. A higher priority task preempts a lower priority task. If not specified, the priority is set to 1. (idle task has the lowest priority, 0.)

#[task(binds = UART0, priority = 1)]
fn uart0(_: uart0::Context) {
    //
}

#[task(binds = UART1, priority = 2)]
fn uart1(_: uart1::Context) {
    //
}

See the RTFM doc for more info.

Shared Resources

Before #[init], we have Resources. These are the late resources we want to initialize at runtime.

struct Resources {
    led: PB7<Output<PushPull>>,
    timer: Timer<stm32::TIM2>,
}

These are like Mutexes we used in a previous experiment.

static LED: Mutex<RefCell<Option<PB7<Output<PushPull>>>>> 
    = Mutex::new(RefCell::new(None));
    
static TIMER_TIM2: Mutex<RefCell<Option<Timer<stm32::TIM2>>>> 
    = Mutex::new(RefCell::new(None));

Instead of Mutex, RTFM uses LateResources. We declare struct Resources for all the resources we want to share across different contexts. These resources must be initialized in init and returned.

struct Resources {
    led: PB7<Output<PushPull>>,
    timer: Timer<stm32::TIM2>,
}

#[init]
fn init(cx: init::Context) -> init::LateResources {
    let rcc = cx.device.RCC.constrain();
    let clocks = rcc.cfgr.freeze();

    // Set up the LED
    let gpiob = cx.device.GPIOB.split();
    let led = gpiob.pb7.into_push_pull_output();

    // Set up the timer
    let mut timer = Timer::tim2(cx.device.TIM2, 5.hz(), clocks);
    timer.listen(Event::TimeOut);

    // Initialization of late resources
    init::LateResources { led, timer }
}

(* If we don’t have late resources, we don’t need to return anything.)

The resources can be safely accessed in tasks. Let’s look at our TIM2 interrupt handler.

#[task(binds = TIM2, resources = [timer, led])]
fn tim2(cx: tim2::Context) {
    cx.resources.timer.clear_interrupt(Event::TimeOut);
    cx.resources.led.toggle().unwrap();
}

resources = [timer, led]) defines which resources we want to use in this context. We can access them by following a path from context to resources: cx.resources.timer, cx.resources.led.

In this interrupt handler, we, using the shared resources, clear the interrupt flag and toggle the LED just like non RTFM version.

That’s it. Our first experiment with RTFM. I am liking this framework. I will explore more in future projects.

ADC: Injected Conversion Mode

2020-05-15T15:15:41+00:00

Our embedded Rust experiments on STM32 platform continues. This week, we explore ADC’s injected conversion mode. The application note AN3116 explains what injected conversion mode is.

This mode is intended for use when conversion is triggered by an external event or by software. The injected group has priority over the regular channel group. It interrupts the conversion of the current channel in the regular channel group.

Injected conversions can be triggered by software or by hardware (timers or external pins). Injected conversions have higher priority and they can interrupt regular conversions immediately. A use case I can think of is that we run regular sequence conversion in a loop or something and interrupt that when needed.

Components

Hardware

Nucleo-F429ZI
Potentiometer

Crates

stm32f4xx-hal A Rust embedded-hal HAL for all MCUs in the STM32 F4 family

Code

The code is available on GitHub

Implementation

This week’s experiment demonstrates injected conversion mode using a timer as an external trigger source. Here are the things this post covers:

Configure Timer (the trigger source) in PWM mode
Configure ADC
- Configure External Trigger source
- Set up an analog input pin
- Configure ADC channel with ADC peripheral and the analog pin
Enable ADC interrupt
Read ADC value in ISR

Configure PWM

One way to configure a timer in PWM mode is to use stm32f4xx-hal’s pwm module. pwm module routes a timer’s output to an output pin. Although output from a pin is not required to use a timer as an external trigger, being able to see the pulse may be helpful for debugging/troubleshooting.

In the code below, we create a pwm instance with TIM1 and set its frequency to 10Hz. This will generate 0.1 seconds pulse.

let pa8 = gpioa.pa8.into_alternate_af1();
let mut pwm = pwm::tim1(dp.TIM1, pa8, clocks, 10.hz());
let max_duty = pwm.get_max_duty();
pwm.set_duty(max_duty / 2);
pwm.enable();

If you don’t want to use stm32f4xx-hal’s pwm module, it is also possible to directly configure a timer in output mode. The code below shows how to select PWM mode 1, set duty, enable the channel, and enable the timer’s main output.

let _tim = Timer::tim1(dp.TIM1, 10.hz(), clocks);
configure_timer1();

// ----

fn configure_timer1() {
    unsafe {
        let tim = &(*TIM1::ptr());
        tim.ccmr1_output()
            .modify(|_, w| w.oc1pe().set_bit().oc1m().pwm_mode1());

        // Set the duty cycle
        tim.ccr1.modify(|_, w| w.ccr().bits(1));
        // Enable the channel
        tim.ccer.modify(|_, w| w.cc1e().set_bit());
        // Enable the TIM main Output
        tim.bdtr.modify(|_, w| w.moe().set_bit());
    }
}

Configure ADC

Next, we configure our ADC in a way it -

starts a conversion when triggered by TIM1
generates an interrupt request upon the end of conversion

We use AdcConfig to do that. Here, we specify the rising edge of TIM1’s signal to be the external trigger source.

let config = AdcConfig::default()
    .end_of_conversion_interrupt(Eoc::Conversion)
    .external_trigger(TriggerMode::RisingEdge, ExternalTrigger::Tim_1_cc_1);
    
let mut adc = Adc::adc1(dp.ADC1, true, config);

We now set up an analog pin and configure ADC channel.

let gpioa = dp.GPIOA.split();
let pa3 = gpioa.pa3.into_analog();
adc.configure_channel(&pa3, Sequence::One, SampleTime::Cycles_112);
adc.enable();

Enable ADC Interrupt

Since we need to access our ADC instance in ISR contexts, we declare a Mutex and move our ADC instance to it after initialization.

static ADC: Mutex<RefCell<Option<Adc<stm32::ADC1>>>> 
    = Mutex::new(RefCell::new(None));

// ----

// Move the shared resource to Mutex
free(|cs| {
    ADC.borrow(cs).replace(Some(adc));
});

Finally, enable ADC interrupt with the NVIC.

unsafe {
    stm32::NVIC::unmask(stm32::interrupt::ADC);
}

Interrupt Handler

That is it. Injected conversion should be triggered on the rising edge of the signal.

The rest is pretty much the same as last week’s ADC experiment. When a conversion is done, EOC end of conversion bit is set and an interrupt request is generated.

In the interrupt handler below, we read the currently available ADC value and print it out. current_sample() reads the result from ADC’s DR register and clears the EOC flag automatically. There is no need to call clear_end_of_conversion_flag().

#[interrupt]
fn ADC() {
    free(|cs| {
        if let Some(ref mut adc) = ADC.borrow(cs).borrow_mut().deref_mut() {
            let sample = adc.current_sample();
            iprintln!(itm(), "PA3: {}", sample);
        }
    });
}

Interrupt Based ADC

2020-05-08T21:11:21+00:00

Polling in a loop is the simplest way to use the ADC. But it makes it difficult to run other codes while the ADC is running. It would be nice if we can make it interrupt-based. This post will show how to do a simple interrupt based ADC in embedded Rust.

Ingredients

Hardware

Nucleo-F429ZI
Potentiometer

Crates

stm32f4xx-hal A Rust embedded-hal HAL for all MCUs in the STM32 F4 family

Code

The code is available on GitHub

EOC Interrupt

Each time ADC completes a conversion, the EOC (End of Conversion) flag is set and the ADC_DR register (the register that holds ADC value) can be read. For this week’s little experiment, we use the EOC flag for interrupts. Just like last week’s ADC project, our output will be PWM. This time, we will adjust the PWM duty cycle in the ISR context instead of the user context.

In stm32f4xx-hal’s adc.rs, the EOC interrupt is disabled by default. We explicitly enable the interrupt using AdcConfig like this.

let config = AdcConfig::default()
    .end_of_conversion_interrupt(Eoc::Conversion);
    
let mut adc = Adc::adc1(dp.ADC1, true, config);

Next, we configure an analog pin and ADC channels. We use only one channel for this example project.

let pa3 = gpioa.pa3.into_analog();
adc.configure_channel(&pa3, Sequence::One, SampleTime::Cycles_112);

We are ready to go. Let’s start ADC. The method below does the following:

Enable ADC
Clear the EOC flag
Set SWSTART bit (which triggers conversion)
Wait until conversion starts.

adc.start_conversion();

Since we want to access ADC module in the interrupt handler, we move adc to Mutex.

free(|cs| {
    ADC.borrow(cs).replace(Some(adc));
});

Don’t forget to enable the ADC interrupt in the NVIC (Nested Vector Interrupt Controller).

unsafe {
    stm32::NVIC::unmask(stm32::interrupt::ADC);
}

Interrupt Handler

The ADC interrupt is now enabled. Whenever the EOC flag is set, it generates an interrupt request and calls up this interrupt handler.

#[interrupt]
fn ADC() {
    free(|cs| {
        if let (Some(ref mut adc), Some(ref mut pwm)) = (
            ADC.borrow(cs).borrow_mut().deref_mut(),
            PWM.borrow(cs).borrow_mut().deref_mut(),
        ) {
            // Reading the result from the ADC_DR clears the EOC flag automatically.
            let sample = adc.current_sample();
            let scale = sample as f32 / 0x0FFF as f32;
            pwm.set_duty((scale * pwm.get_max_duty() as f32) as u16);
            // restart ADC conversion
            adc.start_conversion();
        }
    });
}

In the handler, we take the ADC module out of Mutex and call current_sample(). This method reads from the ADC_DR register and clears the EOC flag. We update the PWM duty cycle based on the ADC value, and finally, restart the conversion by calling start_conversion() before we move out of the ISR.

That’s it! Now our main looks like the code below. There is nothing in the loop. ADC reading and PWM adjustment are all happening in the ISR.

#[entry]
fn main() -> ! {
    let dp = stm32::Peripherals::take().unwrap();
    let rcc = dp.RCC.constrain();
    let clocks = rcc.cfgr.freeze();
    let gpioa = dp.GPIOA.split();

    // Configure PWM
    let pa8 = gpioa.pa8.into_alternate_af1();
    let mut pwm = pwm::tim1(dp.TIM1, pa8, clocks, 50.hz());
    pwm.enable();

    // Configure ADC
    let config = AdcConfig::default().end_of_conversion_interrupt(Eoc::Conversion);
    let mut adc = Adc::adc1(dp.ADC1, true, config);
    let pa3 = gpioa.pa3.into_analog();
    adc.configure_channel(&pa3, Sequence::One, SampleTime::Cycles_112);
    adc.start_conversion();

    // Move shared resources to Mutex
    free(|cs| {
        ADC.borrow(cs).replace(Some(adc));
        PWM.borrow(cs).replace(Some(pwm));
    });

    // Enable interrupt
    unsafe {
        stm32::NVIC::unmask(stm32::interrupt::ADC);
    }

    loop {}
}

ADC to PWM: The World Beyond ON/OFF

2020-05-01T22:11:21+00:00

After playing around with DigitalIO, Timer Counter, Interrupt, I2C, and SPI, I thought it was time to work on Analog Digital Conversion.

To experiment with embedded Rust ADC, I did a quick project that adjusted PWM duty cycle based on ADC values. There were no fancy analog sensors in my toy box. I used a potentiometer and monitored PWM outputs on my oscilloscope.

Although it was such a simple project, I found it really satisfying to see pulses respond to my turning the potentiometer. It was quite a different experience from toggling an LED. As my sensei Tom Igoe says, knowing whether a cat is on or off a mat is not always enough. Sometimes, we want to know how fat the cat is.

While a digital input to a microcontroller can tell you about discrete changes in the physical world, such as whether the cat is on the mat, or the cat is off the mat, there are times when this is not enough. Sometimes you want to know how fat the cat on the mat is. - Tom Igoe

Ingredients

Hardware

Nucleo-F429ZI
Potentiometer

Crates

stm32f4xx-hal A Rust embedded-hal HAL for all MCUs in the STM32 F4 family

Code

The code is available on GitHub

Implementation

ADC

In order to use ADC on STM32 devices, we need to do the followings:

Enable the ADC clock
Enable the GPIO clock
Configure the GPIO pin as an analog input
Configure the ADC (clock, resolution, data alignment, etc.)

It sounded like a lot of work. But it turned out that ADC was as easy as ABC thanks to stm32f4xx-hal. After importing all the required modules, below was all I needed to enable and configure ADC.

let mut adc = Adc::adc1(dp.ADC1, true, AdcConfig::default());

I was curious to know what AdcConfig’s Default was. I looked up the doc and found this.

impl Default for AdcConfig {
    fn default() -> Self {
        Self {
            clock: Clock::Pclk2_div_2,
            resolution: Resolution::Twelve,
            align: Align::Right,
            scan: Scan::Disabled,
            external_trigger: (TriggerMode::Disabled, ExternalTrigger::Tim_1_cc_1),
            continuous: Continuous::Single,
            dma: Dma::Disabled,
            end_of_conversion_interrupt: Eoc::Disabled,
            default_sample_time: SampleTime::Cycles_480,
        }
    }
}

You can, of course, customize AdcConfig. But for this simple experiment, I only wanted to do one-shot conversion. No scanning, no external triggers, no DMA… I didn’t change anything.

After enabling ADC, I configured an analog input pin, PA3.

let gpioa = dp.GPIOA.split();
let pa3 = gpioa.pa3.into_analog();

I passed my pin pa3 to read() method to read a value on the pin.

let sample = adc.read(&mut pa3).unwrap();
iprintln!(itm(), "PA3: {}", sample);

Nucleo-F429ZI has 12 bit ADCs. So, a returned value from read() can be 0 ~ 4095. If you want to convert that to voltage, stm32f4xx-hal has a convenient method for that. Just pass the read value to fn sample_to_millivolts(&self, sample: u16) -> u16.

let millivolts = adc.sample_to_millivolts(sample);
iprintln!(itm(), "PA3: {}mV", millivolts);

PWM

I have to say I got lucky. A couple of days ago, the stm32f4xx-hal team released a new version, v0.8.0, and added PWM support. Without this update, it would have been difficult for me to do PWM.

I haven’t taken a close look at the PWM API yet. But it seems like we just need to pass a Timer, a pin (or pins), clocks, and desired frequency to create a PWM instance.

I initialized my PWM instance with PA8 pin and enabled it like this:

let pa8 = gpioa.pa8.into_alternate_af1();
let mut pwm = pwm::tim1(dp.TIM1, pa8, clocks, 50.hz());
pwm.enable();

My understanding is that the PWM period is determined based on clock configuration. get_max_duty() returns the maximum value you can pass to set_duty() method.

let max_duty = pwm.get_max_duty();
pwm.set_duty(max_duty); // 100% duty cycle
pwm.set_duty(0); // 0% duty cycle

ADC -> PWM

After configuring ADC and PWM, I repeated the followings in the infinite loop.

Read an ADC value
Scale the 12 bit ADC value to the range of 0 to max_duty
Set PWM duty

loop {
    let sample = match adc.read(&mut pa3) {
        Ok(x) => x,
        Err(_) => continue,
    };
    let scale = sample as f32 / 0x0FFF as f32;
    pwm.set_duty((scale * max_duty as f32) as u16);
}

That was it. Simple ADC and PWM with stm32f4xx-hal. I will explore other ADC features in future projects.

How to Measure Distance With Maxbotix Ultrasonic Sensor

2020-04-23T00:11:21+00:00

This week, I played around with an ultrasonic range finder and wrote a little library for it in Rust. The outcome is shown in the image above. This system measures the distance between myself and Ferris.

I used an ultrasonic sensor from Maxbotix to measure distance. This project monitors the sensor’s output and shows the measured distance on a LED display.

Here are two new things I learned from this project:

How to read microcontroller’s timer counter value
How to convert u32 (sensor reading) to &str (for the display) in a no-std environment where format! macro is not available

Ingredients

Hardware

Nucleo-F429ZI
Maxbotix RangeFinder LV-EZ1
LED display (custom made)
Ferris Plushie 🦀

Crates

stm32f4xx-hal A Rust embedded-hal HAL for all MCUs in the STM32 F4 family
max6955 A platform agnostic driver to interface with MAX6955 LED Display Driver (See my post about this driver.)
heapless Heapless, static friendly data structures

Ultrasonic Sensor

Maxbotix ultrasonic sensor measures distance and outputs the reading through PWM or Analog. For this project, I read pulse width with a timer.

The output from the sensor looks like the screenshot below. The pulse width represents distance. You can learn more about pulse width based distance calculation at Maxbotix website.

Reading the pulse width is straightforward. Basically, I observe the state of the input pin and read the timer counter value. When read method is called, it goes like this:

Wait while the pin is low
Reset the counter
Wait while the pin is high
Read the counter value and return it to the caller

Implementation

Three Sensor Models

The sensor comes in 3 models: LV, XL, and HR. They all work the same way. Just different resolutions. To calculate the distance, we use the model-specific scale factor.

LV: 147uS/inch
XL: 58uS/cm
HR: 1uS/mm

I define an enum called Model like this:

impl Model {
    /// scale factor
    fn factor(self) -> u32 {
        match self {
            Model::LV => 147,
            Model::XL => 58,
            Model::HR => 1,
        }
    }
    /// unit
    fn unit(self) -> &str {
        match self {
            Model::LV => "\"",
            Model::XL => "cm",
            Model::HR => "mm",
        }
    }
}

Distance measurement using timer counter

I wrote a module called maxsonar to measure the pulse width by reading a timer’s counter value.

Here is the struct for the sensor. It takes a Timer (concrete TIM2 of the HAL crate), Model, and generic T: InputPin.

pub struct MaxSonar<T> {
    timer: TIM2,
    model: Model,
    pin: T,
}

impl<T, E> MaxSonar<T>
where
    T: InputPin<Error = E>,
    E: core::fmt::Debug,
{
    pub fn new(timer: TIM2, model: Model, pin: T, sysclk: Hertz) -> Self {
        // Configure timer for 1Mhz
        let rcc = unsafe { &(*RCC::ptr()) };
        rcc.apb1enr.modify(|_, w| w.tim2en().set_bit());
        let psc = (sysclk.0 / 1_000_000) as u16;
        timer.psc.write(|w| w.psc().bits(psc - 1));
        timer.egr.write(|w| w.ug().set_bit());
        // Start MaxSonar
        let mut sonar = MaxSonar { timer, model, pin };
        sonar.start();
        sonar
    }

    fn start(&mut self) {
        self.timer.cnt.reset();
        self.timer.cr1.write(|w| w.cen().set_bit());
    }
}

It looks like stm32f4xx-hal doesn’t implement a method to read the current timer value. So, I directly access TIM2’s cnt register in my read method.

pub fn read(&mut self) -> u32 {
    while self.pin.is_low().unwrap() {}
    self.timer.cnt.reset();
    while self.pin.is_high().unwrap() {}
    self.timer.cnt.read().bits() / self.model.factor()
}

As you can see, I do these:

Wait while the pin is low
Reset the counter
Wait while the pin is high
Read the counter value

I then calculate the distance by dividing the counter value by the scale factor. self.model.factor() returns the scale factor of the chosen model. In this project, I use Model::LV. So, the factor is 147.

format! in a no-std environment

Great. I now have the distance as u32. I just need to convert it to &str to show it on my LED display. Here is the definition of the display driver’s write_str method:

pub fn write_str(&mut self, text: &str) -> Result<(), E> 

In a std environment, I would just call format! to make a &str. But, apparently I cannot do that in a no-std environment. After a struggle to find a way to convert u32 to &str, I managed to achieve that with heapless crate. With heapless::String and write! macro, I can create formatted texts.

use core::fmt::Write;
use heapless::consts::*;
use heapless::String;

let mut data = String::<U8>::new();

loop {
    let distance = sonar.read();
    let _ = write!(data, "{:7}{}", distance, sonar.unit());
    max6955.write_str(&data).unwrap();
    data.clear();
}

sonar.unit() returns the unit for the chosen model. So, it is " here.

The code is available on GitHub

GPIO Interrupt: Let Me Know When You Need Me

2020-04-17T12:16:21+00:00

After the successful timer interrupt experiments, I worked on GPIO interrupts this week.

For STM32 microcontrollers, we use EXTI (external interrupt controller) and do these to configure GPIO interrupts:

Enable peripheral clocks.
Configure an input pin and set the edge detection.
Unmask the interrupt mask register.

Once properly configured, an interrupt request is generated when the selected edge occurs on the external interrupt line.

In this post, I will show 3 example programs that demonstrate GPIO interrupt.

GPIO interrupt with one button
GPIO interrupt with two buttons and how to tell which one triggers an interrupt
Interrupt with two buttons in a different way

The goal is to control LEDs when buttons are pressed. I used Nucleo-F429ZI and stm32f4xx-hal for all three of them.

Example 1: Interrupt with One Button

Enable peripheral clocks

First, we need to turn on SYSCFG (System Configuration) peripheral.

let mut dp = stm32::Peripherals::take().unwrap();
dp.RCC.apb2enr.write(|w| w.syscfgen().enabled());

Configure a LED and a button

I need to access my button and LED in both ISR and user contexts. So, I wrap them with Mutex. Note that the initial values are None here. I will replace them with initialized instances later.

static BUTTON: Mutex<RefCell<Option<PC13<Input<PullDown>>>>> = Mutex::new(RefCell::new(None));
static LED: Mutex<RefCell<Option<PB7<Output<PushPull>>>>> = Mutex::new(RefCell::new(None));

Nucleo-F429ZI’s pin pc13 is connected to the user button. After setting it up as a pull down input, I set the edge detection to RISING.

let gpioc = dp.GPIOC.split();
let mut user_button = gpioc.pc13.into_pull_down_input();
user_button.make_interrupt_source(&mut dp.SYSCFG);
user_button.enable_interrupt(&mut dp.EXTI);
user_button.trigger_on_edge(&mut dp.EXTI, Edge::RISING);

I also set up my LED.

let gpiob = dp.GPIOB.split();
let led = gpiob.pb7.into_push_pull_output();

I now move my initialized button and LED to Mutex. Moving the shared resources to Mutex makes it possible to access the LED and the button in both ISR and user contexts. I use critical section with cortex_m::interrupt::free and replace the shared resources’ content (None) with user_button and led.

free(|cs| {
    BUTTON.borrow(cs).replace(Some(user_button));
    LED.borrow(cs).replace(Some(led));
});

Unmask and enable interrupt

Interrupt can be enabled by unmasking NVIC’s register.

unsafe {
    stm32::NVIC::unmask(stm32::interrupt::EXTI15_10);
}

EXTI15_10 means interrupt lines from 10 - 15. Whenever an interrupt is triggered on these lines (my button pc13 is on line 13), EXTI calls this handler.

#[interrupt]
fn EXTI15_10() {
    free(|cs| {
        if let Some(ref mut btn) = BUTTON.borrow(cs).borrow_mut().deref_mut() {
            btn.clear_interrupt_pending_bit();

            if let Some(ref mut led) = LED.borrow(cs).borrow_mut().deref_mut() {
                led.toggle().unwrap();
            }
        }
    });
}

Here, I clear the interrupt flag by calling btn.clear_interrupt_pending_bit() and toggle the LED. (If I don’t clear the flag, it keeps calling the interrupt handler.)

Example 1 full code

Example 2: Interrupt with Two Buttons

Ok, that was pretty easy. But, as I said, EXTI15_10 means interrupt requests can be generated from any of six lines. In the example above, we know it is BUTTON that triggers an interrupt because there are no other buttons. But, what if we have two buttons and want to call different functions depending on which button is pressed? My second example handles interrupt requests from two buttons.

Configure resources

This time, I declare two sets of button/LED.

static BUTTON: Mutex<RefCell<Option<PC13<Input<PullDown>>>>> = Mutex::new(RefCell::new(None));
static LED: Mutex<RefCell<Option<PB7<Output<PushPull>>>>> = Mutex::new(RefCell::new(None));
static ANOTHER_BUTTON: Mutex<RefCell<Option<PC10<Input<PullUp>>>>> = Mutex::new(RefCell::new(None));
static ANOTHER_LED: Mutex<RefCell<Option<PB14<Output<PushPull>>>>> = Mutex::new(RefCell::new(None));

I also declare a Mutex for the external interrupt controller.

static EXTI: Mutex<RefCell<Option<stm32::EXTI>>> = Mutex::new(RefCell::new(None));

Just like the first example, I configure buttons and LEDs. I then wrap my resources with Mutex. This time, I wrap an instance of the external interrupt controller as well. I need EXTI to determine where an interrupt request is generated in the ISR.

let exti = dp.EXTI; // External Interrupt Controller

free(|cs| {
    BUTTON.borrow(cs).replace(Some(user_button));
    LED.borrow(cs).replace(Some(led));
    ANOTHER_BUTTON.borrow(cs).replace(Some(another_button));
    ANOTHER_LED.borrow(cs).replace(Some(another_led));
    EXTI.borrow(cs).replace(Some(exti));
});

Find out where the interrupt comes from

I now have two buttons: one on line 10 and the other on line 13. I want to find out which button is pressed and call a corresponding callback function. Here are my two callback functions.

fn user_button_cb() {
    free(|cs| {
        if let Some(ref mut btn) = BUTTON.borrow(cs).borrow_mut().deref_mut() {
            // Clear the interrupt flag
            btn.clear_interrupt_pending_bit();

            if let Some(ref mut led) = LED.borrow(cs).borrow_mut().deref_mut() {
                led.toggle().unwrap();
            }
        }
    });
}

fn another_button_cb() {
    free(|cs| {
        if let Some(ref mut btn) = ANOTHER_BUTTON.borrow(cs).borrow_mut().deref_mut() {
            // Clear the interrupt flag
            btn.clear_interrupt_pending_bit();

            if let Some(ref mut led) = ANOTHER_LED.borrow(cs).borrow_mut().deref_mut() {
                led.toggle().unwrap();
            }
        }
    });
}

And this is how my interrupt handler tells which button is pressed.

#[interrupt]
fn EXTI15_10() {
    free(|cs| {
        if let Some(ref mut exti) = EXTI.borrow(cs).borrow_mut().deref_mut() {
            let pr = exti.pr.read();
            // Interrupt on line 13?
            if pr.pr13().bit_is_set() {
                user_button_cb();
            }
            // Interrupt on line 10?
            if pr.pr10().bit_is_set() {
                another_button_cb();
            }
        }
    });
}

When an interrupt is triggered, the pending bit corresponding to the interrupt line is set. In the interrupt handler, I evaluate the external interrupt controller’s PR register and call a corresponding callback.

Example 2 full code

Example 3: Another Way of Two Buttons

Example 2 works fine. But, if I touch EXTI’s PR register, I can easily clear interrupt flags by directly writing to it. As we see in example 2, when an interrupt is triggered, the pending bit corresponding to the interrupt line is set. This request can be reset by writing a 1 in the pending register. Actually, stm32f4xx-hal’s clear_interrupt_pending_bit() method does exactly that:

fn clear_interrupt_pending_bit(&mut self) {
    unsafe { (*EXTI::ptr()).pr.write(|w| w.bits(1 << self.i) ) };
}

I am accessing EXTI anyway. Why don’t I clear the flag by directly writing to the PR register?

#[interrupt]
fn EXTI15_10() {
    free(|cs| {
        if let Some(ref mut exti) = EXTI.borrow(cs).borrow_mut().deref_mut() {
            let pr = exti.pr.read();
            // Interrupt on line 13?
            if pr.pr13().bit_is_set() {
                // Clear the interrupt flag
                exti.pr.write(|w| w.pr13().set_bit());
                user_button_cb();
            }
            // Interrupt on line 10?
            if pr.pr10().bit_is_set() {
                // Clear the interrupt flag
                exti.pr.write(|w| w.pr10().set_bit());
                another_button_cb();
            }
        }
    });
}

Since exti.pr.write(|w| w.pr13().set_bit()); clears the interrupt flag, I no longer need to call my button’s clear_interrupt_pending_bit() in my callbacks.

fn user_button_cb() {
    free(|cs| {
        if let Some(ref mut led) = LED.borrow(cs).borrow_mut().deref_mut() {
            led.toggle().unwrap();
        }
    });
}

fn another_button_cb() {
    free(|cs| {
        if let Some(ref mut led) = ANOTHER_LED.borrow(cs).borrow_mut().deref_mut() {
            led.toggle().unwrap();
        }
    });
}

If I do it this way, I don’t even need Mutex for my buttons anymore. Once I configure the buttons and enable the interrupt, they generate interrupt requests and I can access them through EXTI. I don’t need my buttons in the interrupt handler. So, my shared resources are now just LEDs and EXTI.

static LED: Mutex<RefCell<Option<PB7<Output<PushPull>>>>> = Mutex::new(RefCell::new(None));
static ANOTHER_LED: Mutex<RefCell<Option<PB14<Output<PushPull>>>>> = Mutex::new(RefCell::new(None));
static EXTI: Mutex<RefCell<Option<stm32::EXTI>>> = Mutex::new(RefCell::new(None));

Example 3 full code

LSM9DS1: Using a Trait to Support SPI and I2C Interfaces

2020-04-10T15:16:21+00:00

LSM9DS1 is a 9 axis motion sensor module that comes with accelerometer, gyroscope, magnetometer, and temperature sensor. A cool thing about this device is that it has I2C and SPI interfaces. In this post, I will show how I supported both interfaces with trait.

Supporting SPI and I2C interfaces

My first idea was to have two different constructors (one for SPI and the other for I2C) and implement the corresponding read and write methods like spi_write(), i2c_write() at the highest level. But, it didn’t sound right. There would be too many duplicates… So, I decided to solve the problem with a generic trait object.

Generic interface

First, I defined a trait named Interface.

/// Interface Trait. `SpiInterface` and `I2cInterface` implement this.
pub trait Interface {
    type Error;

    /// Writes a byte to a sensor's specified register address.
    /// # Arguments
    /// * `sensor` - `Sensor` to talk to
    /// * `addr` - register address
    /// * `value` - value to write
    fn write(&mut self, sensor: Sensor, addr: u8, value: u8) -> Result<(), Self::Error>;
    /// Reads multiple bytes from a sensor's specified register address.
    /// # Arguments
    /// * `sensor` - `Sensor` to talk to
    /// * `addr` - register address
    /// * `buffer` - buffer to store read data
    fn read(&mut self, sensor: Sensor, addr: u8, buffer: &mut [u8]) -> Result<(), Self::Error>;
}

As you can see, there is no real implementation here. This only defines shared behaviors that are meant to be implemented by SPI and I2C types.

Implementing a trait on a type

Now let’s look at SPI and I2C structs. SPI uses chip select pins to address a device to talk to while I2C communicates with a device by specifying its address. So, the structs for SPI and I2C are very different. They take completely different arguments.

Here is how I defined SpiInterface type and its init method.

/// This combines the SPI Interface and chip select pins
pub struct SpiInterface<SPI, AG, M> {
    spi: SPI,
    ag_cs: AG,
    m_cs: M,
}

impl<SPI, AG, M, CommE, PinE> SpiInterface<SPI, AG, M>
where
    SPI: Transfer<u8, Error = CommE> + Write<u8, Error = CommE>,
    AG: OutputPin<Error = PinE>,
    M: OutputPin<Error = PinE>,
{
    /// Initializes an Interface with `SPI` instance and AG and M chip select `OutputPin`s
    /// # Arguments
    /// * `spi` - SPI instance
    /// * `ag_cs` - Chip Select pin for Accelerometer/Gyroscope
    /// * `m_cs` - Chip Select pin for Magnetometer
    pub fn init(spi: SPI, ag_cs: AG, m_cs: M) -> Self {
        Self { spi, ag_cs, m_cs }
    }
}

And here is I2cInterface. It takes I2C addresses.

/// This holds `I2C` and AG and Mag addresses
pub struct I2cInterface<I2C> {
    i2c: I2C,
    ag_addr: u8,
    mag_addr: u8,
}

impl<I2C> I2cInterface<I2C> {
    /// Initializes an Interface with `I2C` instance and AG and Mag addresses
    /// # Arguments
    /// * `i2C` - I2C instance
    /// * `ag_addr` - `AgAddress`: register address for Accelerometer/Gyroscope
    /// * `mag_addr` - `MagAddress`: register address for Magnetometer
    pub fn init(i2c: I2C, ag_addr: AgAddress, mag_addr: MagAddress) -> Self {
        Self {
            i2c,
            ag_addr: ag_addr.addr(),
            mag_addr: mag_addr.addr(),
        }
    }
}

Although the two interfaces are very different, I can make them both Interface by implementing Interface’s write and read methods.

Here is the implementation of Interface on SpiInterface. You can see how it controls the chip select pins and communicates.

impl<SPI, AG, M, CommE, PinE> Interface for SpiInterface<SPI, AG, M>
where
    SPI: Transfer<u8, Error = CommE> + Write<u8, Error = CommE>,
    AG: OutputPin<Error = PinE>,
    M: OutputPin<Error = PinE>,
{
    type Error = Error<CommE, PinE>;

    fn write(&mut self, sensor: Sensor, addr: u8, value: u8) -> Result<(), Self::Error> {
        let bytes = [addr, value];
        match sensor {
            Accelerometer | Gyro | Temperature => {
                self.ag_cs.set_low().map_err(Error::Pin)?;
                self.spi.write(&bytes).map_err(Error::Comm)?;
                self.ag_cs.set_high().map_err(Error::Pin)?;
            }
            Magnetometer => {
                self.m_cs.set_low().map_err(Error::Pin)?;
                self.spi.write(&bytes).map_err(Error::Comm)?;
                self.m_cs.set_high().map_err(Error::Pin)?;
            }
        }
        Ok(())
    }

    fn read(&mut self, sensor: Sensor, addr: u8, buffer: &mut [u8]) -> Result<(), Self::Error> {
        match sensor {
            Accelerometer | Gyro | Temperature => {
                self.ag_cs.set_low().map_err(Error::Pin)?;
                self.spi.write(&[SPI_READ | addr]).map_err(Error::Comm)?;
                self.spi.transfer(buffer).map_err(Error::Comm)?;
                self.ag_cs.set_high().map_err(Error::Pin)?;
            }
            Magnetometer => {
                self.m_cs.set_low().map_err(Error::Pin)?;
                self.spi
                    .write(&[SPI_READ | MS_BIT | addr])
                    .map_err(Error::Comm)?;
                self.spi.transfer(buffer).map_err(Error::Comm)?;
                self.m_cs.set_high().map_err(Error::Pin)?;
            }
        }
        Ok(())
    }
}

And here is the implementation on I2cInterface. No chip select pins here. This uses an I2C address to specify a sensor.

impl<I2C, CommE> Interface for I2cInterface<I2C>
where
    I2C: WriteRead<Error = CommE> + Write<Error = CommE>,
{
    type Error = Error<CommE>;

    fn write(&mut self, sensor: Sensor, addr: u8, value: u8) -> Result<(), Self::Error> {
        let sensor_addr = match sensor {
            Accelerometer | Gyro | Temperature => self.ag_addr,
            Magnetometer => self.mag_addr,
        };
        core::prelude::v1::Ok(
            self.i2c
                .write(sensor_addr, &[addr, value])
                .map_err(Error::Comm)?,
        )
    }

    fn read(&mut self, sensor: Sensor, addr: u8, buffer: &mut [u8]) -> Result<(), Self::Error> {
        let sensor_addr = match sensor {
            Accelerometer | Gyro | Temperature => self.ag_addr,
            Magnetometer => self.mag_addr,
        };
        core::prelude::v1::Ok(
            self.i2c
                .write_read(sensor_addr, &[addr], buffer)
                .map_err(Error::Comm)?,
        )
    }
}

Init LSM9DS1 driver with generic

Because both SpiInterface and I2cinterface are now Interface, I can init my driver with generic T: Interface instead of a concrete SPI/I2C type.

pub struct LSM9DS1<T>
where
    T: Interface,
{
    interface: T,
    accel: AccelSettings,
    gyro: GyroSettings,
    mag: MagSettings,
}

The fact that it takes Interface means that I can pass either SpiInterface or I2cInterface to instantiate the driver. This way, when I talk to a sensor, I can simply call self.interface.write() or self.interface.read().

For example, here is how to get a temperature measurement. It uses a chosen interface to communicate.

pub fn read_temp(&mut self) -> Result<f32, T::Error> {
    let mut bytes = [0u8; 2];
    self.interface.read(
        Sensor::Accelerometer,
        register::AG::OUT_TEMP_L.addr(),
        &mut bytes,
    )?;
    let result: i16 = (bytes[1] as i16) << 8 | bytes[0] as i16;
    Ok((result as f32) / TEMP_SCALE + TEMP_BIAS)
}

Once I pass the interface to LSM9DS1 driver, I don’t need to worry about if uses SPI or I2C. There is no need to implement separate methods for SPI and I2C. Pretty cool.

Here is the GitHub repo if you are interested.

One more thing…

I found this trait technique really powerful. As an experiment, I also made a fake interface that could be used for testing. This struct implements Interface and has arrays that mimic registers. I can read and write these fake registers through the APIs.

In the end, I did testing at lower levels and didn’t really need this interface. But, I learned a lot in the process. I feel much more comfortable with trait now.

//! Fake Interface for unit tests
use super::Interface;
use super::Sensor;
use Sensor::*;

/// Errors in this crate
#[derive(Debug)]
pub enum Error {
    /// Communication error
    Invalid,
}

/// This holds fake registers
pub struct FakeInterface {
    ag_registers: [u8; 256],
    mag_registers: [u8; 256],
}

impl Default for FakeInterface {
    fn default() -> Self {
        FakeInterface {
            ag_registers: [0u8; 256],
            mag_registers: [0u8; 256],
        }
    }
}

impl FakeInterface {
    /// create a fake interface
    pub fn new() -> Self {
        Default::default()
    }
}

/// Implementation of `Interface`
impl Interface for FakeInterface {
    type Error = Error;

    fn write(&mut self, sensor: Sensor, addr: u8, value: u8) -> Result<(), Self::Error> {
        match sensor {
            Accelerometer | Gyro | Temperature => self.ag_registers[addr as usize] = value,
            Magnetometer => self.mag_registers[addr as usize] = value,
        }
        Ok(())
    }

    fn read(&mut self, sensor: Sensor, addr: u8, buffer: &mut [u8]) -> Result<(), Self::Error> {
        let registers = match sensor {
            Accelerometer | Gyro | Temperature => self.ag_registers,
            Magnetometer => self.mag_registers,
        };
        for i in 0..buffer.len() {
            buffer[i] = registers[(addr as usize) + i];
        }
        Ok(())
    }
}

Timer Interrupt: In the Blink of an Eye

2020-04-04T11:07:21+00:00

As my daily routine was interrupted by COVID-19, I stayed home and played around with embedded Rust’s interrupt this week.

Interrupt can be dangerous if you don’t do it right. I read the concurrency section of the book and learned Rust’s safe way to share resources between the main and ISR contexts.

How to use timer interrupt

In this post, I will show how I did a blinking LED application using a timer interrupt.

“It’s amazing in the blink of an eye, you finally see the light.” - Steven Tyler

1. Wrap shared resources

The goal is to flip the desired state of a LED in an interrupt handler and turn on/off the LED accordingly in the main. So, it is necessary to share the state of LED and a timer peripheral between ISR and the main code.

In embedded Rust, we use statically allocated Mutex to share peripherals and variables between different contexts.

Here is how I wrap bool that represents the state of my LED.

static LED_STATE: Mutex<Cell<bool>> = Mutex::new(Cell::new(false));

And a line below shows how I wrap my TIM2, timer 2 module. Note that TIMER_TIM2’s RefCell has an initial value of None. It will be replaced with a timer peripheral later.

static TIMER_TIM2: Mutex<RefCell<Option<Timer<stm32::TIM2>>>> = Mutex::new(RefCell::new(None));

Next, I set up an interrupt timer. I am setting it up as a 5Hz timer and wrapping it with Mutex.

let mut timer = Timer::tim2(dp.TIM2, 5.hz(), clocks, &mut rcc.apb1);
timer.listen(Event::Update);

I then use critical section with cortex_m::interrupt::free and replace TIMER_TIM2’s content (None) with my instantiated timer.

free(|cs| {
    TIMER_TIM2.borrow(cs).replace(Some(timer));
});

2. Handle interrupts

Enabling the TIM2 interrupt is very easy with NVIC (Nested vector interrupt control).

stm32::NVIC::unpend(Interrupt::TIM2);
unsafe {
    stm32::NVIC::unmask(Interrupt::TIM2);
}

That’s it. The timer is now running. When the interrupt is triggered, it goes to the interrupt handler defined like this:

#[interrupt]
fn TIM2() {
    free(|cs| {
        if let Some(ref mut tim2) = TIMER_TIM2.borrow(cs).borrow_mut().deref_mut() {
            tim2.clear_update_interrupt_flag();
        }
        let led_state = LED_STATE.borrow(cs);
        led_state.replace(!led_state.get());
    });
}

The first thing to do in the ISR is to clear the interrupt flag. stm32f3xx_hal has clear_update_interrupt_flag(). This method clears the status register’s UIF bit. This bit is set by the hardware and must be cleared by the software. If this bit is not cleared, the program repeats the ISR forever. After clearing the flag, I flip the state of LED_STATE and replace the old value with a new one.

3. Reflect the change in the main

In the main, I evaluate LED_STATE like this:

loop {
    if free(|cs| LED_STATE.borrow(cs).get()) {
        led.set_high().unwrap();
    } else {
        led.set_low().unwrap();
    }
}

See how I use critical section by calling cortex_m::interrupt::free to access LED_STATE. This and Mutex ensure exclusive access to the shared resource.

Code: Blink Blink

Here are two codes for the blinking LED. One for STM32F3DISCOVERY board and the other for Nucleo-F429ZI. I used stm32f3xx_hal for DISCOVERY and stm32f4xx_hal for Nucleo. The basic concept is the same between the two implementations. Only differences are the way to instantiate the timer peripheral and the call to clear the interrupt flag by using HAL specific methods.

STM32F3DISCOVERY

Here is the code for STM32F3DISCOVERY board board. This is built with stm32f3xx_hal.

GitHub repo

#![no_main]
#![no_std]

extern crate panic_halt;

use core::cell::{Cell, RefCell};
use core::ops::DerefMut;
use cortex_m;
use cortex_m::interrupt::{free, Mutex};
use cortex_m_rt::entry;
use stm32f3xx_hal::{
    prelude::*,
    stm32,
    stm32::{interrupt, Interrupt},
    timer::{Event, Timer},
};

static LED_STATE: Mutex<Cell<bool>> = Mutex::new(Cell::new(false));
static TIMER_TIM2: Mutex<RefCell<Option<Timer<stm32::TIM2>>>> = Mutex::new(RefCell::new(None));

#[interrupt]
fn TIM2() {
    free(|cs| {
        if let Some(ref mut tim2) = TIMER_TIM2.borrow(cs).borrow_mut().deref_mut() {
            tim2.clear_update_interrupt_flag();
        }
        let led_state = LED_STATE.borrow(cs);
        led_state.replace(!led_state.get());
    });
}

#[entry]
fn main() -> ! {
    let dp = stm32::Peripherals::take().unwrap();
    // Set up the system clock
    let mut flash = dp.FLASH.constrain();
    let mut rcc = dp.RCC.constrain();
    let clocks = rcc.cfgr.freeze(&mut flash.acr);

    // Set up the LED
    let mut gpioe = dp.GPIOE.split(&mut rcc.ahb);
    let mut led = gpioe
        .pe9
        .into_push_pull_output(&mut gpioe.moder, &mut gpioe.otyper);

    // Set up the interrupt timer
    let mut timer = Timer::tim2(dp.TIM2, 5.hz(), clocks, &mut rcc.apb1);
    timer.listen(Event::Update);

    // Move shared resources to Mutex
    free(|cs| {
        TIMER_TIM2.borrow(cs).replace(Some(timer));
    });

    // Enable interrupt
    stm32::NVIC::unpend(Interrupt::TIM2);
    unsafe {
        stm32::NVIC::unmask(Interrupt::TIM2);
    }

    loop {
        if free(|cs| LED_STATE.borrow(cs).get()) {
            led.set_high().unwrap();
        } else {
            led.set_low().unwrap();
        }
    }
}

Nucleo-F429ZI

Nucleo-F429ZI board has STM32F429 microcontroller. I use stm32f4xx_hal for this.

GitHub repo

#![no_main]
#![no_std]

extern crate panic_halt;

use core::cell::{Cell, RefCell};
use core::ops::DerefMut;
use cortex_m;
use cortex_m::interrupt::{free, Mutex};
use cortex_m_rt::entry;
use stm32f4xx_hal::{
    prelude::*,
    stm32,
    stm32::interrupt,
    timer::{Event, Timer},
};

static LED_STATE: Mutex<Cell<bool>> = Mutex::new(Cell::new(false));
static TIMER_TIM2: Mutex<RefCell<Option<Timer<stm32::TIM2>>>> = Mutex::new(RefCell::new(None));

#[interrupt]
fn TIM2() {
    free(|cs| {
        if let Some(ref mut tim2) = TIMER_TIM2.borrow(cs).borrow_mut().deref_mut() {
            tim2.clear_interrupt(Event::TimeOut);
        }
        let led_state = LED_STATE.borrow(cs);
        led_state.replace(!led_state.get());
    });
}

#[entry]
fn main() -> ! {
    let dp = stm32::Peripherals::take().unwrap();
    // Set up the LED
    let gpiob = dp.GPIOB.split();
    let mut led = gpiob.pb7.into_push_pull_output();

    // Set up the system clock
    let rcc = dp.RCC.constrain();
    let clocks = rcc.cfgr.sysclk(48.mhz()).freeze();

    // Set up the interrupt timer
    let mut timer = Timer::tim2(dp.TIM2, 5.hz(), clocks);
    timer.listen(Event::TimeOut);

    free(|cs| {
        TIMER_TIM2.borrow(cs).replace(Some(timer));
    });

    // Enable interrupt
    stm32::NVIC::unpend(stm32::Interrupt::TIM2);
    unsafe {
        stm32::NVIC::unmask(stm32::Interrupt::TIM2);
    }

    loop {
        if free(|cs| LED_STATE.borrow(cs).get()) {
            led.set_high().unwrap();
        } else {
            led.set_low().unwrap();
        }
    }
}

Alone on a Mountaintop

Schedule Software Tasks With RTFM

Implementation

Schedule a task to run sometime in the future

NVIC as a dispatcher

Serial Communication with RTFM

Implementation

BBQueue: A SPSC, lockless, no_std, thread safe, queue

USART and Timer Resources

Interrupt Handlers

Rust’s Real Time For the Masses (RTFM): Between bare metal and Real Time OS

Timer interrupt with RTFM

Implementation

Attributes

1.app

2. init

3. idle

4. task

Shared Resources

ADC: Injected Conversion Mode

Components

Implementation

Configure PWM

Configure ADC

Enable ADC Interrupt

Interrupt Handler

Interrupt Based ADC

Ingredients

EOC Interrupt

Interrupt Handler

ADC to PWM: The World Beyond ON/OFF

Ingredients

Implementation

ADC

PWM

ADC -> PWM

How to Measure Distance With Maxbotix Ultrasonic Sensor

Ingredients

Hardware

Crates

Ultrasonic Sensor

Implementation

Three Sensor Models

Distance measurement using timer counter

format! in a no-std environment

GPIO Interrupt: Let Me Know When You Need Me

Example 1: Interrupt with One Button

Enable peripheral clocks

Configure a LED and a button

Unmask and enable interrupt

Example 2: Interrupt with Two Buttons

Configure resources

Find out where the interrupt comes from

Example 3: Another Way of Two Buttons

LSM9DS1: Using a Trait to Support SPI and I2C Interfaces

Supporting SPI and I2C interfaces

Generic interface

Implementing a trait on a type

Init LSM9DS1 driver with generic

One more thing…

Timer Interrupt: In the Blink of an Eye

How to use timer interrupt

1. Wrap shared resources

2. Handle interrupts

3. Reflect the change in the main

Code: Blink Blink

STM32F3DISCOVERY

Nucleo-F429ZI

1.`app`

2. `init`

3. `idle`

4. `task`