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     uint8_t result = get_nibble(data, sizeof(data), 0);
  16     fail_unless(copy_bits_right_aligned(data, 4, 4, 12, result, 4));
  17
  18 ## 8 Byte Bitfield Decoding
  19
  20     uint64_t data = 0x8000000000000000;
  21     uint64_t result = get_bit_field(data, 0, 1, false);
  22     // result == 0x1
  23
  24     data = 0x0402574d555a0401;
  25     result = get_bit_field(data, 16, 32, false);
  26     // result = 0x574d555a;
  27
  28     data = 0x00000000F34DFCFF;
  29     result = nth_byte(data, 0);
  30     //result = 0x0
  31
  32     result = nth_byte(data, 4);
  33     //result = 0xF3
  34
  35 ## 8 Byte Bitfield Encoding
  36
  37     uint64_t data = 0;
  38     fail_unless(set_bit_field(&data, 1, 0, 1));
  39     uint64_t result = get_bit_field(data, 0, 1, false);
  40     ck_assert_int_eq(result, 0x1);
  41
  42 TODO setting bit fields is just copying
  43
  44 ## CAN Signal Encoding
  45
  46 The library supports encoding floating point CAN signals as well as booleans
  47 into a uint64_t payload.
  48
  49     uint64_t payload = bitfield_encode_float(1, 1, 3, 1, 0)
  50     // payload == 0x1000000000000000
  51
  52     payload = bitfield_encode_bool(true, 1, 3);
  53     // payload == 0x1000000000000000
  54
  55 ## CAN Signal Decoding
  56
  57 The library supports parsing floating point CAN signals as well as booleans.
  58
  59     uint64_t payload = 0xeb00000000000000;
  60     float float_result = bitfield_parse_float(payload,
  61             2, // starting bit
  62             4, // width of the signal's field
  63             1001.0, // transformation factor for the signal value
  64             -30000.0); // transformation offset for the signal value
  65     // float_result == -19990.0
  66
  67     bool bool_result = bitfield_parse_bool(payload,
  68             0, // starting bit
  69             1, // width of the signal's field
  70             1.0, // transformation factor for the signal value
  71             0); // transformation offset for the signal value
  72     // bool_result == true
  73
  74 ## Testing
  75
  76 The library includes a test suite that uses the `check` C unit test library.
  77
  78     $ make test
  79
  80 ## Authors
  81
  82 Chris Peplin cpeplin@ford.com
  83
  84 ## License
  85
  86 Copyright (c) 2013 Ford Motor Company
  87
  88 Licensed under the BSD license.