Test all canutil functions and document in README.

3 files changed, 47 insertions, 13 deletions

diff --git a/src/canutil/read.h b/src/canutil/read.h
index 028b03a6..865bb278 100644
--- a/src/canutil/read.h
+++ b/src/canutil/read.h
@@ -10,20 +10,28 @@ extern "C" {
 
 /* Public: Parse a CAN signal from a message and apply required transformation.
  *
- * signal - The details of the signal to decode and forward.
- * data   - The raw bytes of the CAN message that contains the signal, assumed
- *      to be in big-endian byte order from CAN.
+ * data - the payload containing the signal.
+ * bit_offset - the starting bit for the signal.
+ * bit_size - the width of the signal.
+ * factor - the transformation factor for the signal value, applied after
+ *      pulling out the bit field. Use 1.0 for no factor.
+ * offset - the transformation offset for the signal value, applied after
+ *      pulling out the bit field. Use 0 for no offset.
  *
- * Returns the final, transformed value of the signal.
+ * Returns the decoded and transformed value of the signal.
  */
 float bitfield_parse_float(uint64_t data, uint8_t bit_offset, uint8_t bit_size,
         float factor, float offset);
 
 /* Public: Parse a CAN signal from a message and interpret it as a boolean.
  *
- * signal - The details of the signal to decode and forward.
- * data   - The raw bytes of the CAN message that contains the signal, assumed
- *      to be in big-endian byte order from CAN.
+ * data - the payload containing the signal.
+ * bit_offset - the starting bit for the signal.
+ * bit_size - the width of the signal.
+ * factor - the transformation factor for the signal value, applied after
+ *      pulling out the bit field. Use 1.0 for no factor.
+ * offset - the transformation offset for the signal value, applied after
+ *      pulling out the bit field. Use 0 for no offset.
  *
  * Returns false if the value was 0, otherwise true.
  */
diff --git a/src/canutil/write.c b/src/canutil/write.c
index 14d2a449..583c2513 100644
--- a/src/canutil/write.c
+++ b/src/canutil/write.c
@@ -9,11 +9,13 @@ uint64_t bitfield_encode_float(float value, uint8_t bit_offset, uint8_t bit_size
         raw += 0.5;
     }
     uint64_t result = 0;
-    set_bit_field(&result, (uint64_t)raw, bit_offset, bit_size);
+    if(!set_bit_field(&result, (uint64_t)raw, bit_offset, bit_size)) {
+        // debug("%f will not fit in a %d bit field", value, bit_size);
+    }
     return result;
 }
 
-uint64_t bitfield_encode_bool(bool value, uint8_t bit_offset, uint8_t bit_size,
-        float factor, float offset) {
-    return bitfield_encode_float(value, offset, factor, bit_offset, bit_size);
+uint64_t bitfield_encode_bool(const bool value, const uint8_t bit_offset,
+        const uint8_t bit_size) {
+    return bitfield_encode_float(value, bit_offset, bit_size, 1.0, 0);
 }
diff --git a/src/canutil/write.h b/src/canutil/write.h
index 3d13b1df..f117a06c 100644
--- a/src/canutil/write.h
+++ b/src/canutil/write.h
@@ -8,11 +8,35 @@
 extern "C" {
 #endif
 
+/* Public: Encode a floating point number into a fixed point, fixed bit width
+ *      field in a bit array.
+ *
+ * value - the floating point value to encode.
+ * bit_offset - the starting point for the encoded bits in the returned value.
+ * bit_size - The max width of the field in the resulting bit array. If bit_size
+ *      isn't big enough to store the fixed point version of the value, the bitfeld
+ *      will *not* be set. TODO some error reporting would be nice.
+ * factor - a factor used to transform from floating to fixed point before
+ *      encoding. Use 1.0 for no factor.
+ * offset - an offset used to transform from floating to fixed point before
+ *      encoding. Use 0 for no offset.
+ *
+ * Returns a big-endian uint64_t with the value encoded as a bitfield.
+ */
 uint64_t bitfield_encode_float(float value, uint8_t bit_offset, uint8_t bit_size,
                 float factor, float offset);
 
-uint64_t bitfield_encode_bool(bool value, uint8_t bit_offset, uint8_t bit_size,
-                float factor, float offset);
+/* Public: Encode a boolean into fixed bit width field in a bit array.
+ *
+ * value - the boolean value to encode - true will be 1, false will be 0.
+ * bit_offset - the starting point for the encoded bits in the returned value.
+ * bit_size - The max width of the field in the resulting bit array. If bit_size
+ *      isn't big enough to store the fixed point version of the value, the bitfeld
+ *      will *not* be set. TODO some error reporting would be nice.
+ *
+ * Returns a big-endian uint64_t with the value encoded as a bitfield.
+ */
+uint64_t bitfield_encode_bool(const bool value, const uint8_t bit_offset, const uint8_t bit_size);
 
 #ifdef __cplusplus
 }