CANiBUS

Overview

The CANiBUS Server connects one or more CAN devices to one or more researchers. The CANiBUS Server has drivers for each CAN device that abstracts the communication with the client. It provides a method for multiple researchers to connect to a Vehicle and work together to analyze the CANbus system. This allows for an unlimited number of research to work without additional strain on the electrical system of the vehicle. This works well for instructional environment or remote research on a vehicle.

!!!NOTE!!! This is VERY ALPHA. It may cause unexpected results to your vehicle, which may include but are not limited to: stalling, bricking the system, locking the brakes, or becoming a Decepticon. We can not be held responsible for the use of this product.

Server Features

• Currently supported CAN Devices:
  • CANSIM - CAN bus simulator (built-in)
  • ELM32x - (Initial support)
  • ( more devices will be added as the server matures )

• Lobby
  • Lists available connected CAN devices
  • Group chat for discussion prior to starting
  • Ability to start a 'hack session' on a device

• Hack Sessions
  • Read-only mode (instructor mode)
  • Chat private to that hack session

Usage

./canibusd <port> - Defaults to port 1234

ELM327 CAN Devices

These are serial devices (regardless of USB, Bluetooth, etc) For Canibus to detect this you need to create a symlink for /dev/obdX. Example:

ln -s /dev/ttyUSB0 /dev/obd0

Then start canibusd or use the client to /rescan for the new devices.

Client

The protocol is documented on the wiki so any client can connect (or bot for that matter). The network protocol is XML an fairly self documenting but you will want to refer to the server source or the wiki if you want to write your own. There is a built-in ncurses client in the client/ folder. This code can be used as an example on how to implement some of the APIs. Ncurses was chosen because:

• Simple interface
• Works via SSH
• Could be used as a server admin tool for CANiBUS server maintenance

Commands

Usage

./canibus <server> <port>

Default server is localhost

Default port is 1234

Lobby

• Type anything to chat
• /nick <name> to change username
• /quit to exit
• /refresh to request to server to rescan for newly attached CAN devices
• /join <can device #>

Config Screen

• /start - In a config screen starts the session
• /leave - Exit back to lobby

Session

• /start - starts monitoring
• /stop - stops monitoring
• /filter <arbId> - sets and arbitration ID filter
• /leave - Exit back to lobby

Source Code

Get the source here: https://github.com/Hive13/CANiBUS

Client Development

Server Version

The protocol to the network socket is XML based. When you connect you will get a server version response:

<canibusd><server version="0.0.1"/></canibusd>

All packets are wrapped in <canibusd> tags and all have a \n at the end of them.

The first thing you *must* do is register your username. All commands to the server a simple ascii commands that begin with a '.'

Register a Name

.n<Name> = Example: .nBob The response: Your clientId, updateHackSesisonList, and a finishedInit (see below)

You can also use .n<Name> later to change the username

Once you have registered a name you will be in the "Lobby" state. Here you can start a hack session on one of the returned canbus IDs listed in the updateHackSessionList or chat with other users.

Chatting

Just send a packet. Do *NOT* start with a '.' a straight string will be treated as a chat message and will send to the appropriate scope. If in a lobby it goes to the lobby, if in a hack session then it will only go to the other members of that hack session.

Response example for "hi":

<canibusd><msg type="chat" clientid="1" author="Bob" value="hi"/></canibusd>

Exiting To gracefully quit out and disconnect from the CANIBUSd server you simply execute:

.X

You will be disconnected and all other attached users will see:

<canibusd><deleteclient clientid="1"/></canibusd>

Which simply states which client has recently left so that you can clean up any memory they were using.

Joining a Session To Join a session (or start one) use the can device id

.sj#

This will send you configuration options and you will be in Config mode.

Starting a session

.ss

Start Monitoring

.sm

Stop Monitoring

.sM

Set Arbitration ID Filter

.sfa<filter>

Exit a session but not the connection

.x

Responses

Responses can come at any time. Along with the above XML responses here are some other standard update responses.

client

<canibusd><client clientid="1" cookie=""/></canibusd>

This message only gets sent when you register your name for the first time. This is just to inform you of what your client ID number is and has a place for a cookie. A cookie will be used for reconnecting a disconnected session but is not currently implemented.

UpdateHackSessionList

<canibusd>
 <updatehacksessionlist type="full">
    <canbus id="1" type="CANSIM" description="CAN Simulation Module"/>
  </updatehacksessionlist>
</canibusd>

Additional linefeeds added for clarity but are not present in the actual packet. This provides a list of CAN devices the server knows about. You can get a new list at any time by sending: .sl This is fairly self explanatory but note that you can have any number of canbuses present. You wll use the canbus ID to connect and start hack sessions.

ClientUpdate

When you first connect you will get a client update for everyone attached to the server:

<canibusd> <clientupdate clientid="1" host="localhost.localdomain" name="Bob" session="-1"/></canibusd>

Keep a local copy of this information in your application so you will know what has changed. The first time you see these messages just record them as is. After you see the FinishedInit message (below) then all following ClientUpdates are for changes or new people joining. Information is fairly self-explanatory and session means what active HackSession they belong to.

For instance if Bob in this example changed their name (via .n<name>) you would get a message like this:

<canibusd> <clientupdate clientid="1" name="Steve"/></canibusd> 

As you can see it only has the updated information as attributes. Newly joined users will have all attributes shown.

Other possible attributes

• master - Bool value. If client is a master of a session (Not really used)

Session

This is a hack session.

<session id="1" canbusid="1 clients="1" private="0"/></updatehacksessionlist>

ID is the session id, canbusId is which CAN device this session is working with. Clients is the number of active clients in this session. Private is a private hack session or one that is full.

FinishedInit

After the initial barrage of XML packets comes in you will get the following packet:

<canibusd><finishedinit /></canibusd>

This just signals to the client that all data after this point is update data and not initialization data.

HackSessionUpdate

Update information about a hack session

<hacksessionupdate sessionid="1" description="" master="1" maxclients="20" private="0" clients="1"/>

SessionID is the id of the session. Description is a user defined topic/description. Master is the Client ID of the master of this session. MaxClients is the max amount of clients allowed to join before the session becomes private. Private is if the session is a private session or has reached its max clients. Clients is the current number of joined clients.

DeleteSession

Removes a session all together

<deletesession sessionid="1" />

ConfigUpdate

When starting or joining a hack session you will have a moment to set additional configuration options for that session. You will get a packet with config options available to that session and that device.

<configupdate sessionid="1">
  <option type="bool" title="Read only mode" command=".seR" value="0" edit="1"/>
</configupdate>

If you receive a config update then your client should be able to view the hack sessions config data. Formatting was done for legibility. You can receive multiple options of type: bool, integer, string. The Tile is the name of the option. Command is the command necessary to set the option. Value is the default value for the option. Edit is a bool attribute to notify the client if their client ID has access to modify this attribute or if it is just a read-only state.

When you are done configuring you should issue the command to start the session.

Packet

This is an actual CAN packet sent from the device.

<packet seq="1" receivetime="1.054677" relativetime="0.04398" error="0" transmitted="0" networkname="MS CAN" arbid="123" extended="0" size=5 changed="2" b1="23" b2="23" b3="23" b4="27" b5="21" />

Seq is the sequence number the packet was received. ReceiveTime is the absolute time. Relative Time is time since last packet. Error is boolean if an error was detected on the bus. Transmitted is a boolean if a member of the hacksession transmitted this packet. Network Name is a human name associated with this bus. ArbId is the arbitration ID of the packet. Extended is a boolean to denote if the packet is an extended can message. Size is the packet size. B1-B8 are the bytes in hex for the packets. Changed is a bit value of what byte has changed 1 == b1, 2 == b2, 4 == b3, etc.

See Also

• VRL Hive13
• http://opengarages.org/