Document that accel_raw and accel_norm expect data to be ready

[jacobrosenthal]

Were chatting over at https://github.com/BenBergman/lis3dh-rs

Most people dont understand that if you're polling, you need to be setting an appropriate data rate so that you're not requesting data before its ready.Really what you should be doing when polling in a tight loop is

            while !lis3dh.is_data_ready().unwrap() {}
            let dat = lis3dh.accel_raw().unwrap();

But if thats what you should be doing, should accel_raw just include that check directly?

It adds an extra round trip which might annoy some zero costers. And it would generally be implemented with some kind of WouldBlock non error which might be confusing/

Currently accel_raw doesnt specify.

I did a github search found one brave soul out of all the implementations who did exactly that
https://github.com/JosephBGerber/lis3dsh-rs/blob/5ef60fa5d95199df18fcfb20d6ea1a2e810c36b7/src/lib.rs

I think its worth implementers to weight in here

[tarcieri]

AccelRaw is a relatively new trait split from Accelerometer. It doesn’t have a particularly well-specified contract, but I’d say is generally assumed to be synchronous, so I’d suggest incorporating the busy-wait logic.

All that said, I think there is a lot of opportunity for specifying abstractions for other usage patterns, particularly interrupt-driven ones.

If you have any suggestions about any of these things, I’d love to hear them.

[jacobrosenthal]

Yeah i was about to say it could be very common to get your data is ready signal from an interrupt, which means you dont want the extra check. Might be enough to document that its not expected _raw or _norm are validated for data is ready and explain the interrupt and polling patterns

[jacobrosenthal]

Its a shame no one watches here. You should look at your downstream dependencies authors and ask them to star and watch so they can be kept in the loop :)

[tarcieri]

If there are specific GitHub issues or other resources you can link, I’d be curious to check them out. Separately it might be good to try to upstream this crate to the Embedded WG so there’s somewhere better to coordinate on improvements.

[jacobrosenthal]

https://crates.io/crates/accelerometer/reverse_dependencies

…

On Fri, Jul 31, 2020, 9:02 PM Tony Arcieri ***@***.***> wrote: If there are specific GitHub issues or other resources you can link, I’d be curious to check them out. Separately it might be good to try to upstream this crate to the Embedded WG so there’s somewhere better to coordinate on improvements. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#61 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADPI5G2RRHKNYAXAEIFRSLR6OHV5ANCNFSM4PRK7UQQ> .

[jacobrosenthal]

Beyond that I just used https://github.com/search?l=Rust&q=accel_raw&type=Code