• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Rust Spidev
2
3[![Build Status](https://github.com/rust-embedded/rust-spidev/workflows/CI/badge.svg)](https://github.com/rust-embedded/rust-spidev/actions)
4[![Version](https://img.shields.io/crates/v/spidev.svg)](https://crates.io/crates/spidev)
5[![License](https://img.shields.io/crates/l/spidev.svg)](https://github.com/rust-embedded/rust-spidev/blob/master/README.md#license)
6![Minimum Supported Rust Version](https://img.shields.io/badge/rustc-1.69.0+-blue.svg)
7
8[Documentation](https://docs.rs/spidev)
9
10The Rust `spidev` seeks to provide full access to the Linux spidev
11device in Rust without the need to wrap any C code or directly make
12low-level system calls.  The documentation for the spidev interace can
13be found at <https://www.kernel.org/doc/Documentation/spi/spidev>.
14
15## Example/API
16
17The following is not an exhaustive demonstration of the Spidev
18interface but provides a pretty good idea of how to use the library in
19practice.
20
21```rust
22extern crate spidev;
23use std::io;
24use std::io::prelude::*;
25use spidev::{Spidev, SpidevOptions, SpidevTransfer, SpiModeFlags};
26
27fn create_spi() -> io::Result<Spidev> {
28    let mut spi = Spidev::open("/dev/spidev0.0")?;
29    let options = SpidevOptions::new()
30         .bits_per_word(8)
31         .max_speed_hz(20_000)
32         .mode(SpiModeFlags::SPI_MODE_0)
33         .build();
34    spi.configure(&options)?;
35    Ok(spi)
36}
37
38/// perform half duplex operations using Read and Write traits
39fn half_duplex(spi: &mut Spidev) -> io::Result<()> {
40    let mut rx_buf = [0_u8; 10];
41    spi.write(&[0x01, 0x02, 0x03])?;
42    spi.read(&mut rx_buf)?;
43    println!("{:?}", rx_buf);
44    Ok(())
45}
46
47/// Perform full duplex operations using Ioctl
48fn full_duplex(spi: &mut Spidev) -> io::Result<()> {
49    // "write" transfers are also reads at the same time with
50    // the read having the same length as the write
51    let tx_buf = [0x01, 0x02, 0x03];
52    let mut rx_buf = [0; 3];
53    {
54        let mut transfer = SpidevTransfer::read_write(&tx_buf, &mut rx_buf);
55        spi.transfer(&mut transfer)?;
56    }
57    println!("{:?}", rx_buf);
58    Ok(())
59}
60
61fn main() {
62    let mut spi = create_spi().unwrap();
63    println!("{:?}", half_duplex(&mut spi).unwrap());
64    println!("{:?}", full_duplex(&mut spi).unwrap());
65}
66```
67
68## Features
69
70The following features are implemented and planned for the library:
71
72- [x] Implement the Read trait
73- [x] Implement the Write trait
74- [x] Support for full-duplex transfers
75- [x] Support for configuring spidev device
76- [x] Support for querying spidev configuration state
77
78## Minimum Supported Rust Version (MSRV)
79
80This crate is guaranteed to compile on stable Rust 1.69.0 and up.  It *might*
81compile with older versions but that may change in any new patch release.
82
83## Cross Compiling
84
85Most likely, the machine you are running on is not your development
86machine (although it could be).  In those cases, you will need to
87cross-compile.  The following basic instructions should work for the
88raspberry pi or beaglebone black:
89
901. Install rust and cargo
912. Install an appropriate cross compiler.  On an Ubuntu system, this
92   can be done by doing `sudo apt-get install g++-arm-linux-gnueabihf`.
933. Build or install rust for your target.  This is necessary in order
94   to have libstd available for your target.  For arm-linux-gnueabihf,
95   you can find binaries at <https://github.com/japaric/ruststrap>.
96   With this approach or building it yourself, you will need to copy
97   the ${rust}/lib/rustlib/arm-unknown-linux-gnueabihf to your system
98   rust library folder (it is namespaced by triple, so it shouldn't
99   break anything).
1004. Tell cargo how to link by adding the lines below to your
101   ~/.cargo/config file.
1025. Run your build `cargo build --target=arm-unknown-linux-gnueabi`.
103
104The following snippet added to my ~/.cargo/config worked for me:
105
106```
107[target.arm-unknown-linux-gnueabihf]
108linker = "arm-linux-gnueabihf-gcc"
109```
110
111## License
112
113Licensed under either of
114
115- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
116  <http://www.apache.org/licenses/LICENSE-2.0>)
117- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
118
119at your option.
120
121### Contribution
122
123Unless you explicitly state otherwise, any contribution intentionally submitted
124for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
125dual licensed as above, without any additional terms or conditions.
126
127## Code of Conduct
128
129Contribution to this crate is organized under the terms of the [Rust Code of
130Conduct][CoC], the maintainer of this crate, the [Embedded Linux Team][team], promises
131to intervene to uphold that code of conduct.
132
133[CoC]: CODE_OF_CONDUCT.md
134[team]: https://github.com/rust-embedded/wg#the-embedded-linux-team
135