1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
//! LS7366 Buffer encoder interface using `embedded_hal`.
//!
//! This driver should work with any SPI interface as long as it implements
//! the blocking `embedded_hal` [`SPI traits`].
//!
//! The library is built with `no_std`.
//!
//!
//! # Examples
//! Bare-minimum boilerplate to read from the buffer:
//! ```no_run
//!   use ls7366::Ls7366;
//! // --- snip ---
//! # use std::error::Error;
//! #
//! # use rppal::spi::{Bus, Mode, SlaveSelect, Spi};
//! #
//! # use std::thread::sleep;
//! # use std::time::Duration;
//! # fn main() {
//! #    // create an instance of an SPI object
//! #    // In this case, the buffer is on SPI0 and SS1.
//! #    // The chip acts in Mode0.
//! #    let some_hal_spi_object = Spi::new(Bus::Spi0, SlaveSelect::Ss1, 14_000_000, Mode::Mode0).unwrap();
//! #
//!     // Construct a driver instance from the SPI interface, using default chip configurations.
//!     let mut spi_driver = Ls7366::new(some_hal_spi_object).unwrap();
//!
//!     // Loop and read the counter.
//!     loop {
//!         let result = spi_driver.get_count().unwrap();
//!         sleep(Duration::from_secs(1));
//!         println!("read data:= {:?}", result);
//!     }
//! // --- snip ---
//! # }
//! ```
//! ## Advanced configuration
//! The LS7366 has two registers dedicated to configuring the chip's various functions:
//! [`Mdr0`] and [`Mdr1`].
//!
//! Configuring the chip can be accomplished by writing into these two registers.
//!
//! **Manually configuring these registers is **not** required when using [`Ls7366::new`].**
//!
//! 1. Build an instance of [`Mdr0`] and [`Mdr1`] with the desired configuration.
//! 2. Write these instances into the relevant registers.
//! ```
//! use ls7366::mdr0::{QuadCountMode, CycleCountMode, FilterClockDivisionFactor,IndexMode, Mdr0};
//! use ls7366::mdr1::{CounterMode, Mdr1};
//! use ls7366::{Ls7366, Target, Encodable};
//! use embedded_hal_mock::spi::Mock;
//! use embedded_hal_mock::spi::Transaction as SpiTransaction;
//! # let expectations = [
//! #     SpiTransaction::write(vec![0b10001000, 0b10100110]),
//! #     SpiTransaction::write(vec![0b10010000, 0b00000101])
//! # ];
//! # let spi = Mock::new(&expectations);
//! # let mut driver = Ls7366::new_uninit(spi);
//! // --- snip ---
//!     let mdr0_configuration = Mdr0{
//!         quad_count_mode: QuadCountMode::Quad2x,
//!         filter_clock : FilterClockDivisionFactor::Two,
//!         index_mode: IndexMode::ClearCntr,
//!         cycle_count_mode: CycleCountMode::SingleCycle,
//!         is_index_inverted: false
//!     };
//!     let mdr1_configuration = Mdr1{
//!         counter_mode: CounterMode::Byte3,
//!         // --- Snip ---
//!         # disable_counting:true,
//!         # flag_on_bw: false,
//!         # flag_on_idx: false,
//!         # flag_on_cmp: false,
//!         # flag_on_cy: false,
//!     };
//!
//!     driver.write_register(Target::Mdr0, &[mdr0_configuration.encode()]).unwrap();
//!     driver.write_register(Target::Mdr1, &[mdr1_configuration.encode()]).unwrap();
//!
//! ```
//!
//! [`SPI traits`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/blocking/spi/index.html
//! [`Mdr0`]: ./mdr0/struct.Mdr0.html
//! [`Mdr1`]: ./mdr1/struct.Mdr1.html
//! [`Ls7366::new`]: ./struct.Ls7366.html#method.new
#![cfg_attr(not(test), no_std)]

use embedded_hal::blocking::spi::{Transfer, Write};

pub use crate::ir::{Action, Target};
use crate::ir::InstructionRegister;
use crate::str_register::Str;
use crate::traits::Decodable;
pub use crate::traits::Encodable;

pub mod mdr0;
pub mod ir;
pub mod mdr1;
pub mod str_register;
mod traits;
mod errors;
mod utilities;
mod test_instruction_register;

#[derive(Clone, Debug)]
pub enum Error<SpiError> {
    // Underlying SPI interface error
    SpiError(SpiError),
    // Failed to encode / decode payload
    EncodeError(errors::EncoderError),
    // Request to write payload larger than target register.
    PayloadTooBig,
}


impl<E: core::fmt::Debug> core::fmt::Display for Error<E> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}", self)
    }
}

impl<E> From<E> for Error<E> {
    fn from(error: E) -> Self {
        Error::SpiError(error)
    }
}

/// An LS8366 Quadrature encoder buffer
pub struct Ls7366<SPI> {
    /// SPI interface where the buffer is attached.
    interface: SPI,
}

impl<SPI, SpiError> Ls7366<SPI>
    where SPI: Transfer<u8, Error=SpiError> + Write<u8, Error=SpiError> {
    /// Creates a new driver and initializes the Chip to some sensible default values.
    /// This will zero the chip's counter, configure it to 4 byte count mode (full range)
    /// and to treat every 4th quadrature pulse as a increment.
    ///
    /// If the chip is already configured or another configuration is preferable,
    /// use the ([`uninit`]) constructor.
    ///
    /// [`uninit`]: #method.new_uninit
    pub fn new(iface: SPI) -> Result<Self, Error<SpiError>> {
        let mut driver = Ls7366 {
            interface: iface
        };
        // Creating configurations for the two MDR configuration registers
        let mdr0_payload = mdr0::Mdr0 {
            quad_count_mode: mdr0::QuadCountMode::Quad4x,
            cycle_count_mode: mdr0::CycleCountMode::FreeRunning,
            index_mode: mdr0::IndexMode::DisableIndex,
            is_index_inverted: false,
            filter_clock: mdr0::FilterClockDivisionFactor::One,
        };
        let mdr1_payload = mdr1::Mdr1 {
            counter_mode: mdr1::CounterMode::Byte4,
            disable_counting: false,
            flag_on_idx: false,
            flag_on_cmp: false,
            flag_on_bw: false,
            flag_on_cy: false,
        };

        // Write primary configuration to chip.
        driver.write_register(ir::Target::Mdr0, &[mdr0_payload.encode()])?;
        // Write secondary configuration to chip.
        driver.write_register(ir::Target::Mdr1, &[mdr1_payload.encode()])?;
        // Zero Dtr to prepare a write into Cntr.
        driver.write_register(ir::Target::Dtr, &[0x00, 0x00, 0x00, 0x00])?;
        // Load Dtr into Cntr.
        driver.act(
            ir::InstructionRegister {
                target: ir::Target::Cntr,
                action: ir::Action::Load,
            },
            &mut [0x00],
        )?;
        // clear status register.
        driver.clear_status()?;
        Ok(driver)
    }

    /// Creates a new driver but does NOT do any initialization actions against the chip.
    pub fn new_uninit(iface: SPI) -> Self {
        Ls7366 {
            interface: iface
        }
    }
    /// Writes bytes into the specified register. attempting to write more than 4 bytes is an error.
    pub fn write_register(&mut self, target: ir::Target, data: &[u8]) -> Result<(), Error<SpiError>> {
        let ir_cmd = ir::InstructionRegister {
            target,
            action: ir::Action::Write,
        };
        if data.len() > 4 {
            return Err(Error::PayloadTooBig);
        }

        let encoded = ir_cmd.encode();
        let payload: &mut [u8] = &mut [encoded, encoded, encoded, encoded, encoded];

        let mut i = 1;
        for datum in data {
            payload[i] = *datum;
            i+=1;
        }
        // only write as many bits as we had data, +1 for the IR.
        self.interface.write(&payload[0.. data.len()+1])?;
        Ok(())
    }
    /// Executes a read operation against specified register, returning up to 4 bytes from the chip.
    ///
    /// ## Note:
    ///
    /// Reading from [`Str`] clears the register to zero.
    ///
    /// Reading from [`Dtr`] is a Noop.
    ///
    /// Reading from [`Cntr`] overwrites [`Otr`].
    ///
    /// [`Str`]:  ir/enum.Target.html#variant.Str
    /// [`Dtr`]:  ir/enum.Target.html#variant.Dtr
    /// [`Cntr`]: ir/enum.Target.html#variant.Cntr
    /// [`Otr`]:  ir/enum.Target.html#variant.Otr
    pub fn read_register<'a>(&mut self, rx_buffer: &'a mut [u8], target: ir::Target) -> Result<&'a [u8], Error<SpiError>> {
        let ir = ir::InstructionRegister {
            target,
            action: Action::Read,
        };
        let tx_buffer = &mut [ir.encode(), 0x00, 0x00, 0x00, 0x00];

        let result = self.interface.transfer(tx_buffer)?;
        rx_buffer.copy_from_slice(&result[1..]);
        Ok(rx_buffer)
    }
    pub fn get_status(&mut self) -> Result<Str, Error<SpiError>> {
        let result: &mut [u8] = &mut [0x00, 0x00, 0x00, 0x00];
        let raw_result = self.read_register(result, ir::Target::Str)?;
        let result = Str::decode(raw_result[3]);
        match result {
            Ok(data) => Ok(data),
            Err(error) => Err(Error::EncodeError(error)),
        }
    }
    /// Clears the [`Str`] status register to zero.
    ///
    /// [`Str`]:  ir/enum.Target.html#variant.Str
    pub fn clear_status(&mut self) -> Result<(), Error<SpiError>> {
        self.act(
            ir::InstructionRegister {
                target: Target::Str,
                action: Action::Clear,
            }, &mut [0x00],
        )?;
        Ok(())
    }
    /// Reads the chip's current count, sets the sign bit appropriate to the status register
    pub fn get_count(&mut self) -> Result<i64, Error<SpiError>> {
        let raw_result: &mut [u8] = &mut [0x00, 0x00, 0x00, 0x00];
        let raw_result = self.read_register(raw_result,ir::Target::Cntr)?;
        let status = self.get_status()?;
        let count = utilities::vec_to_i64(&raw_result);
        match status.sign_bit {
            str_register::SignBit::Negative => Ok(count * -1),
            str_register::SignBit::Positive => Ok(count),
        }
    }


    /// Performs a transaction against the chip.
    ///
    /// Some actions (e.g. writing to a register) accept up to 4 u8 bytes, this function accepts
    /// the same. Attempt to write more than 4 bytes will result in an ['SpiError.PayloadToBig`]
    ///
    /// Other sources of error responses may arise from the underlying HAL implementation and are
    /// bubbled up.
    pub fn act<'a>(&mut self, command: InstructionRegister, data: &'a mut [u8]) -> Result<& 'a [u8], Error<SpiError>> {
        let tx_buffer: &[u8] = &[command.encode()];
        match command.action {
            Action::Clear | Action::Load => {
                if data.len() > 1 {
                    Err(Error::PayloadTooBig)
                } else {
                    self.interface.write(&tx_buffer)?;
                    Ok(data)
                }
            }
            Action::Read => {
                let mut tx_buffer = [tx_buffer[0], 0x00, 0x00, 0x00, 0x00];
                let result = self.interface.transfer(&mut tx_buffer)?;
                data.copy_from_slice(result);
                Ok(data)
            }
            Action::Write => {
                if data.len() > 5 {
                    Err(Error::PayloadTooBig)
                } else {
                    self.interface.write(&tx_buffer)?;
                    Ok(data)
                }
            }
        }
    }
}