README.mkd

   1 CAN Message Utilities for C
   2 ===========================
   3
   4 This is a C library with functions to help encode and decode Controller Area
   5 Network (CAN) message payloads. Some of the bitfield functions may be useful for
   6 other areas, too.
   7
   8 The header files contain complete function documentation, but to get you
   9 started, here are examples using the API:
  10
  11 ## Bitfield Manipulation
  12
  13     uint8_t data[4] = {0x12, 0x34, 0x56, 0x78};
  14     uint8_t result = get_byte(data, sizeof(data), 0);
  15     // result = 0x12;
  16     result = get_nibble(data, sizeof(data), 0);
  17     // result = 0x1;
  18     bool success = copy_bits_right_aligned(data, 4, 4, 12, result, 4)
  19     // success == true
  20     // result[0] == 0x2
  21     // result[1] == 0x34
  22
  23 ## 8 Byte Bitfield Decoding
  24
  25     uint64_t data = 0x8000000000000000;
  26     uint64_t result = get_bit_field(data, 0, 1, false);
  27     // result == 0x1
  28
  29     data = 0x0402574d555a0401;
  30     result = get_bit_field(data, 16, 32, false);
  31     // result = 0x574d555a;
  32
  33     data = 0x00000000F34DFCFF;
  34     result = eightbyte_get_byte(data, 0, false);
  35     //result = 0x0
  36
  37     result = eightbyte_get_byte(data, 4, false);
  38     //result = 0xF3
  39
  40     result = eightbyte_get_nibble(data, 10, false);
  41     //result = 0x4;
  42
  43 ## 8 Byte Bitfield Encoding
  44
  45     uint64_t data = 0;
  46     fail_unless(set_bit_field(&data, 1, 0, 1));
  47     uint64_t result = get_bit_field(data, 0, 1, false);
  48     ck_assert_int_eq(result, 0x1);
  49
  50 TODO setting bit fields is just copying
  51
  52 ## CAN Signal Encoding
  53
  54 The library supports encoding floating point CAN signals as well as booleans
  55 into a uint64_t payload.
  56
  57     uint64_t payload = bitfield_encode_float(1, 1, 3, 1, 0)
  58     // payload == 0x1000000000000000
  59
  60     payload = bitfield_encode_bool(true, 1, 3);
  61     // payload == 0x1000000000000000
  62
  63 ## CAN Signal Decoding
  64
  65 The library supports parsing floating point CAN signals as well as booleans.
  66
  67     uint64_t payload = 0xeb00000000000000;
  68     float float_result = bitfield_parse_float(payload,
  69             2, // starting bit
  70             4, // width of the signal's field
  71             1001.0, // transformation factor for the signal value
  72             -30000.0); // transformation offset for the signal value
  73     // float_result == -19990.0
  74
  75     bool bool_result = bitfield_parse_bool(payload,
  76             0, // starting bit
  77             1, // width of the signal's field
  78             1.0, // transformation factor for the signal value
  79             0); // transformation offset for the signal value
  80     // bool_result == true
  81
  82 ## Testing
  83
  84 The library includes a test suite that uses the `check` C unit test library.
  85
  86     $ make test
  87
  88 ## Authors
  89
  90 Chris Peplin cpeplin@ford.com
  91
  92 ## License
  93
  94 Copyright (c) 2013 Ford Motor Company
  95
  96 Licensed under the BSD license.