LCAP

         

LCAP Release status: experimental [box doku]
Description	Labor CAN Automation Protocol
Author(s)	Hansinator
Last Version	0 ()
Platform	AVR, PC
License	GPLv2+
Download	SVN, browse

This is an effort to design and implement a new Labor CAN automation protocol.

CAN2.0B

The CAN2.0B standard is the wire protocol used by the LCAP protocol.

Frame Format

• 11 + 18 = 29 Bits identifier
• Remote Transmission Request flag
• 4 Bit Data Length Code
• 0..8 Byte data
• 15 Bits CRC
• ACK slot
• Frame types:
  • Data
  • Remote request
  • Error
  • Overload

Protocol Features

When a CRC error is detected, an error frame is generated by a receiving node 
and the frame is repeated. An ack is generated during the ack slot by at least one receiving node, whether it accepts or discards the message. Messages with lower-valued identifier fields (LSB first) have higher priority. Message collisions may be detected by a lower-priority transmitting node by measuring the bus during identifier transmission, As message identifiers must be unique per device (no two or more devices may send a frame having the same identifier), any collision must result in a different identifier measured by the lower-priority transmitter. In this case the lower-priority message is suppressed and transmission is automatically repeated after the higher-priority message is delivered. A device may send a remote request frame to request a frame with the given identifier.

CAN2.0B Frame Logical View

The following C struct describes the logical view of a CAN2.0B frame. If you're interested in the wire format, check out Wikipedia.

typedef struct
{
  uint32_t id;
  uint8_t dlc;
  uint8_t data[8];
} can_message;

The field "id" is assumed to have the following structure:

• Bit 28:18 -> 11 Bit CAN Standard Identifier
• Bit 17:00 -> 18 Bit CAN Extended Identifier
• (Bit intervals are inclusive)

The field "dlc" is assumed to have the following structure:

• Bit 4 -> Remote Transmission Request (RTR) flag
• Bit 3:0 -> CAN Data Length Code (DLC)

The field data contains 0 to 8 data bytes.

Note: The RTR flag is not present when using the current labor can mcp2515 driver!

LCAP

The LCAP attempts to improve upon the original LAP by simplifying adressing. There is a single subaddress data field instead of a separate source and target port. It provides additional header bits for an acknowledge, very basic long packet transmission, and possible future extensions such as crypto. The standard addressing mode supports virtual devices as target addresses, which may be used for multicast communication to implement a topic based messaging scheme, like netvar. The special request frames are utilized to provide ping and multicast requests.

As the CAN bus is a cooperatively shared medium, no care is taken to prevent bus service disruption such as message flooding. In theory, any node could transmit any message(s) to overload the bus or otherwise disrupt communication.

Message Format (almost final draft)

• CAN2.0B Message ID Bit-Allocation (29Bit from left to right in [std-ident:ext-ident])
  • 8 Bit target address
  • 10 Bit subaddress
  • 8 Bit source device
  • 1 bit (R)ACK flag
  • 1 bit long packet start or sequence bit
    • DLC == 8 && set -> start long packet
    • DLC < 8 && long packet -> stop
    • DLC == 8 && long packet -> sequence bit (toggle)
  • 1 Bit reserved
• 4 Bit DLC (Data Length Code)
• 0..8 Bytes Data

The device source address satisfies the CAN requirement that each message identifier may only be sent by a single device. The DLC field is used in conjunction with the long packet flag to produce special meanings.

Protocol Description (almost final draft)

• Adressing
  • Every device should have an unique address
  • Source address must be a real device
  • Target address may be a virtual multicast address for which there is no device address
  • 0xFF is the broadcast address
  • 0x00 is reserved as the system multicast address
  • Sub-address allocation & usage is free and depends on each target implementation,
    except for the system address and the special control sub-address 0x000
• Flags
  • If reserved bits are not zero, the message must be ignored
  • An ACK flag in a data frame requests an empty data frame from the receiver to the
    transmitter having the RACK flag set if the message was accepted, unset otherwise
    • Multicast addresses ignore ACK flags in data frames
    • If a master exists for a multicast address, it may respond with an empty RACK
      data frame to data frames sent to the topicif it liked the packet
  • The long packet start flag indicates the start of an overly long packet when DLC == 8
    • The flag becomes a sequence bit and is toggled in each long packet chunk
    • Any subsequent data frames with DLC == 8 continue the long packet
    • Shorter frames (DLC < 8) indicate the end of a long packet
    • If the last packet has a length of 8, an additional empty packet must be transmitted
    • May be combined with ACK, so that each chunk must be acknowledged
      (which may be useful to prevent buffer overruns or enforce rate limiting)
    • Multicast addresses may also respond with long packets
• Data frames
  • Payload and DLC may be freely chosen depending on implementation,
    except for long packets, where DLC has a special meaning
  • No frames may be sent from a broadcast address
• Special request frames
  • Requests to a device have the requesting device as target and the requested address as source,
    where broadcast requests shall be ignored
  • Requests to a multicast address have the requested address as target and the device that
    should answer as source or 0xFF if any device may answer
    • In the latter case there must be a multicast-address "master" who should feel responsible
  • All answers are data frames with an identical identifier, except for broadcast ping requests
  • Ping request (ACK flag set)
    • devices answer if the requested sub-address is valid
    • this is also the case for multicast addresses, where the responsible device answers
    • no answer means the target is offline or sub-address is not understood
    • source address 0xFF is a broadcast ping, all devices must answer with their source address
    • every device & topic must be reachable on control sub-address 0x000 or be seen as offline
• The remaining system address and control sub-address functions are defined by the
  automation protocol that is used on the bus

Logical Frame Structure (draft)

The following C struct describes the logical view of an LCAP message.

//flag bit masks
typedef enum { lcap_flag_rsvrd = 0x1, lcap_flag_long = 0x2, lcap_flag_rack = 0x4, lcap_flag_request = 0x8 }  lcap_flags_t;

typedef struct {
  lcap_flags_t flags;
  uint8_t src_addr;
  uint8_t trg_addr;
  uint16_t sub_addr;
  uint8_t len;
  uint8_t *data[];
} lcap_msg_t;

More explanations and hopefully some implementation will follow soon!

Ideas

Configure can chip to use rec buffer 0 for device messages, having one filter set to device address and the other to broadcast use rec buffer 1 for topic messages, supporting pre-filtering of 4 topics or groups