Add get_byte and get_nibble to 8byte function set.

[apps/agl-service-can-low-level.git] / README.mkd

diff --git a/README.mkd b/README.mkd
index 8f6ac5f..0ec5126 100644 (file)
--- a/README.mkd
+++ b/README.mkd
@@ -1,28 +1,83 @@
 CAN Message Utilities for C
-============
+===========================
+
+This is a C library with functions to help encode and decode Controller Area
+Network (CAN) message payloads. Some of the bitfield functions may be useful for
+other areas, too.
+
+The header files contain complete function documentation, but to get you
+started, here are examples using the API:
 
 ## Bitfield Manipulation
 
+    uint8_t data[4] = {0x12, 0x34, 0x56, 0x78};
+    uint8_t result = get_byte(data, sizeof(data), 0);
+    // result = 0x12;
+    result = get_nibble(data, sizeof(data), 0);
+    // result = 0x1;
+    bool success = copy_bits_right_aligned(data, 4, 4, 12, result, 4)
+    // success == true
+    // result[0] == 0x2
+    // result[1] == 0x34
+
+## 8 Byte Bitfield Decoding
+
+    uint64_t data = 0x8000000000000000;
+    uint64_t result = get_bit_field(data, 0, 1, false);
+    // result == 0x1
+
+    data = 0x0402574d555a0401;
+    result = get_bit_field(data, 16, 32, false);
+    // result = 0x574d555a;
+
+    data = 0x00000000F34DFCFF;
+    result = eightbyte_get_byte(data, 0, false);
+    //result = 0x0
+
+    result = eightbyte_get_byte(data, 4, false);
+    //result = 0xF3
+
+    result = eightbyte_get_nibble(data, 10, false);
+    //result = 0x4;
+
+## 8 Byte Bitfield Encoding
+
+    uint64_t data = 0;
+    fail_unless(set_bit_field(&data, 1, 0, 1));
+    uint64_t result = get_bit_field(data, 0, 1, false);
+    ck_assert_int_eq(result, 0x1);
+
+TODO setting bit fields is just copying
+
 ## CAN Signal Encoding
 
+The library supports encoding floating point CAN signals as well as booleans
+into a uint64_t payload.
+
+    uint64_t payload = bitfield_encode_float(1, 1, 3, 1, 0)
+    // payload == 0x1000000000000000
+
+    payload = bitfield_encode_bool(true, 1, 3);
+    // payload == 0x1000000000000000
+
 ## CAN Signal Decoding
 
 The library supports parsing floating point CAN signals as well as booleans.
 
     uint64_t payload = 0xeb00000000000000;
-    float result = bitfield_parse_float(payload,
+    float float_result = bitfield_parse_float(payload,
             2, // starting bit
             4, // width of the signal's field
             1001.0, // transformation factor for the signal value
             -30000.0); // transformation offset for the signal value
-    // result == -19990.0
+    // float_result == -19990.0
 
-    bool result = bitfield_parse_bool(payload,
+    bool bool_result = bitfield_parse_bool(payload,
             0, // starting bit
             1, // width of the signal's field
             1.0, // transformation factor for the signal value
             0); // transformation offset for the signal value
-    // result == true
+    // bool_result == true
 
 ## Testing