Merge pull request #3 from newpavlov/master

Added missing API methods and documentation. Removed internall HidDevice buffer.

Author: Osspial

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "hidapi"
-version = "0.2.0"
-authors = ["Roland Ruckerbauer <[email protected]>", "Osspial <[email protected]"]
+version = "0.3.0"
+authors = ["Roland Ruckerbauer <[email protected]>", "Osspial <[email protected]", "Artyom Pavlov <[email protected]>"]
 repository = "https://github.com/Osspial/hidapi-rs"
 description = "Rust-y wrapper around hidapi"
 license = "LGPL-3.0+"
@@ -10,7 +10,7 @@ build = "build.rs"
 links = "hidapi"
 
 [dependencies]
-libc = "0.1.8"
+libc = "0.2.15"
 
 [build-dependencies]
 gcc = "0.3"

README.md

@@ -2,4 +2,42 @@
 
 This crate provides a rust abstraction over the features of the C library
 [hidapi](https://github.com/signal11/hidapi) by signal11. Based off of
-[hidapi_rust](https://github.com/ruabmbua/hidapi_rust) by ruabmbua.
+[hidapi_rust](https://github.com/ruabmbua/hidapi_rust) by ruabmbua.
+
+# Usage
+
+This crate is [on crates.io](https://crates.io/crates/hidapi) and can be
+used by adding `hidapi` to the dependencies in your project's `Cargo.toml`.
+
+```toml
+[dependencies]
+hidapi = "0.3"
+```
+Example:
+
+```rust
+extern crate hidapi;
+
+let api = hidapi::HidApi::new().unwrap();
+// Print out information about all connected devices
+for device in &api.devices() {
+    println!("{:#?}", device);
+}
+
+// Connect to device using its VID and PID
+let (VID, PID) = (0x0123, 0x3456);
+let device = api.open(VID, PID).unwrap();
+
+// Read data from device
+let mut buf = [0u8; 8];
+let res = device.read(&mut buf[..]).unwrap();
+println!("Read: {:?}", &buf[..res]);
+
+// Write data to device
+let buf = [0u8, 1, 2, 3, 4];
+let res = device.write(&buf).unwrap();
+println!("Wrote: {:?} byte(s)", res);
+```
+
+# Documentation
+You can generate documentation by running `cargo doc` for this crate.

examples/co2mon.rs

@@ -0,0 +1,143 @@
+/****************************************************************************
+    Copyright (c) 2015 Artyom Pavlov All Rights Reserved.
+
+    This file is part of hidapi-rs, based on hidapi_rust by Roland Ruckerbauer.
+    It's also based on the Oleg Bulatov's work (https://github.com/dmage/co2mon)
+
+    hidapi-rs is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    hidapi-rs is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with hidapi-rs.  If not, see <http://www.gnu.org/licenses/>.
+****************************************************************************/
+
+
+//! Opens a KIT MT 8057 CO2 detector and reads data from it. This 
+//! example will not work unless such an HID is plugged in to your system. 
+
+extern crate hidapi;
+
+use hidapi::{HidApi, HidDevice};
+use std::thread::sleep;
+use std::time::Duration;
+
+const CODE_TEMPERATURE: u8 = 0x42;
+const CODE_CONCENTRATION: u8 = 0x50;
+const HID_TIMEOUT: i32 = 5000;
+const RETRY_SEC: u64 = 1;
+const DEV_VID: u16 = 0x04d9;
+const DEV_PID: u16 = 0xa052;
+const PACKET_SIZE: usize = 8;
+
+enum CO2Result {
+    Temperature(f32),
+    Concentration(u16),
+    Unknown(u8, u16),
+    Error(&'static str),
+}
+
+fn decode_temperature(value: u16) -> f32 {
+    (value as f32)*0.0625 - 273.15
+}
+
+fn decode_buf(buf: [u8; PACKET_SIZE]) -> CO2Result {
+    let mut res: [u8; PACKET_SIZE] = [
+        (buf[3] << 5) | (buf[2] >> 3),
+        (buf[2] << 5) | (buf[4] >> 3),
+        (buf[4] << 5) | (buf[0] >> 3),
+        (buf[0] << 5) | (buf[7] >> 3),
+        (buf[7] << 5) | (buf[1] >> 3),
+        (buf[1] << 5) | (buf[6] >> 3),
+        (buf[6] << 5) | (buf[5] >> 3),
+        (buf[5] << 5) | (buf[3] >> 3)
+    ];
+
+    let magic_word = b"Htemp99e";
+    for i in 0..PACKET_SIZE {
+        let sub_val:u8 = (magic_word[i] << 4) | (magic_word[i] >> 4);
+        res[i] = u8::overflowing_sub(res[i], sub_val).0;
+    }
+
+    if res[4] != 0x0d {
+        return CO2Result::Error("Unexpected data (data[4] != 0x0d)");
+    }
+    let checksum = u8::overflowing_add(
+        u8::overflowing_add(res[0], res[1]).0, res[2]).0;
+    if checksum != res[3] {
+        return CO2Result::Error("Checksum error");
+    }
+
+    let val: u16 = ((res[1] as u16) << 8) + res[2] as u16;
+    match res[0] {
+        CODE_TEMPERATURE => CO2Result::Temperature(decode_temperature(val)),
+        CODE_CONCENTRATION => {
+            if val > 3000 {
+                CO2Result::Error(
+                    "Concentration bigger than 3000 (uninitialized device?)")
+            } else {
+                CO2Result::Concentration(val)
+            }
+        },
+        _ => CO2Result::Unknown(res[0], val),
+    }
+}
+
+fn open_device(api: &HidApi) -> HidDevice {
+    loop {
+        match api.open(DEV_VID, DEV_PID) {
+            Ok(dev) => return dev,
+            Err(err) => {
+                println!("{}", err);
+                sleep(Duration::from_secs(RETRY_SEC));
+            },
+        }
+    }
+}
+
+fn main() {
+    let api = HidApi::new().expect("HID API object creation failed");
+
+    let dev = open_device(&api);
+
+    dev.send_feature_report(&[0; PACKET_SIZE]).expect("Feature report failed");
+
+    println!("Manufacurer:\t{}", dev.get_manufacturer_string()
+        .expect("Failed to read manufacurer string"));
+    println!("Product:\t{}", dev.get_product_string()
+        .expect("Failed to read product string"));
+    println!("Serial number:\t{}", dev.get_serial_number_string()
+        .expect("Failed to read serial number"));
+
+    loop {
+        let mut buf = [0; PACKET_SIZE];
+        match dev.read_timeout(&mut buf[..], HID_TIMEOUT) {
+            Ok(PACKET_SIZE) => (),
+            Ok(res) => {
+                println!("Error: unexpected length of data: {}/{}",
+                    res, PACKET_SIZE);
+                continue;
+            },
+            Err(err) => {
+                println!("Error: {:}", err);
+                sleep(Duration::from_secs(RETRY_SEC));
+                continue;
+            }
+        }
+        match decode_buf(buf) {
+            CO2Result::Temperature(val) => println!("Temp:\t{:?}", val),
+            CO2Result::Concentration(val) => println!("Conc:\t{:?}", val),
+            CO2Result::Unknown(..) => (),
+            CO2Result::Error(val) => {
+                println!("Error:\t{}", val);
+                sleep(Duration::from_secs(RETRY_SEC));
+            },
+        }
+    }
+}

examples/lshid.rs

@@ -25,17 +25,11 @@ extern crate hidapi;
 use hidapi::HidApi;
 
 fn main() {
-    
     println!("Printing all available hid devices.");
 
     let api = HidApi::new().unwrap();
 
-    let devices = api.devices();
-
-    for device in &devices {
+    for device in &api.devices() {
         println!("{:#?}", device);
     }
-
-    println!("");
-    
 }

examples/readhid.rs

@@ -28,16 +28,17 @@ use hidapi::HidApi;
 
 fn main() {
 
-    let api = HidApi::new().unwrap();
+    let api = HidApi::new().expect("Failed to create API instance");
 
-    let mut joystick = api.open(1103, 45320).unwrap();
+    let joystick = api.open(1103, 45320).expect("Failed to open device");
 
     loop {
-        let data = joystick.read().unwrap();
+        let mut buf = [0u8; 256];
+        let res = joystick.read(&mut buf[..]).unwrap();
 
         let mut data_string = String::new();
 
-        for u in data {
+        for u in &buf[..res] {
             data_string.push_str(&(u.to_string() + "\t"));
         }