Connect the components 

As a prerequisite to executing this document you will need to have the following kit-list to hand:

Cisco 819 : http://www.cisco.com/c/en/us/products/routers/819-integrated-services-router-isr/index.html

B&B OBD Key (LDVDSV2-S) : http://www.bb-elec.com/Products/Telematics-MRM-Solutions/OBDII-Converters-Gateways/OBDII-Converters.aspx         

OBD Y- Cable : http://www.bb-elec.com/Products/Telematics-MRM-Solutions/OBDII-Converters-Gateways/OBDII-Cables-Accessories.aspx                                   

Smart Serial cable : http://www.amazon.com/Cisco-Router-cable-AS5300-CAB-SS-232FC/dp/B008DJEDO4/ref=sr_1_1?ie=UTF8&qid=1429652075&sr=8-1&keywords=CAB-SS-232FC 

9 pin to 25 pin adapter : http://www.maplin.co.uk/p/maplin-serial-rs232-9-pin-male-to-25-pin-male-adapter-a23qj

Null modem : http://ie.rs-online.com/web/p/d-sub-connector-accessories/2430374/

Following the guideline in the image below, connect the OBDII Streamer to the 819 Router using the blue serial cable. 

The desktop PC must be connected to the 819 Router using the light blue console cable and the 819 itself must be connected to an active network port using an Ethernet cable.

Once these connections are in place the 819 can be powered on.                   

819 Configuration for Key Connectivity

Open the Putty interface.

(If Putty is not already installed it can be downloaded from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)

Use the following connection settings...

Connection/Serial - 'Serial line to connect to' = COM13
Parity = None
Flow control = None 
Session - select 'Serial' 
Click Open to connect
Username/password - Both are set to davra 

The 819 Router must be configured in order to communicate with the B&B ODBII Streamer. 
Type 'conf t'to enter configuration mode and enter the following values, substituting the ip address of the Ruban server where instructed:
 

(config)#interface Loopback0   //this reverse telnets out of the serial portal connected to the ODBII key

(config)#ip address 10.0.0.10 255.255.255.0   
(config)#ip virtual-reassembly in
(config)#no shutdown

(config)#exit

(config)#interface Serial0   //Configures the serial port for asynchronous communication
(config)#physical-layer async
(config)#no ip address
(config)#encapsulation slip

(config)#exit

(config)#line 7
(config)#modem InOut
(config)#no exec
(config)#transport input all
(config)#stopbits 1
(config)#speed 115200
(config)#exit 

(config)#access-list 23 permit 10.10.10.0 0.0.0.7

(config)#end

Now obtain the Router Serial Number using the command 'sh inv'. This will be needed later.

Testing the connection to the OBDII Key

In order to quick test the connectivity to the OBDII key you can execute the following on the 819 router:

NOTE: If the BB_ODBStreamer policy is running, you need to deactivated before proceeding with the steps described bellow.
To stop the policy do the following commands:
conf t
no event manager policy BB_ODBStreamer.tcl
end 

To reactivete again the policy:
conf t
event manager policy BB_ODBStreamer.tcl
end  

Enter, terminal monitor
Enter the command,  clear line 7

Run the tclsh command.

Copy and paste the following script block, follow by the Enter Key:

set allDataReceived 0
set responseReceived 0
set dataReceived 0
proc handleCmdTimeout {} {
global cmdTimeoutId
global allDataReceived
after cancel $cmdTimeoutId 
puts "Response timeout"
set allDataReceived 1
}
proc handleResponse { connection } {
global allDataReceived
global cmdTimeoutId
global responseReceived
global dataReceived
after cancel $cmdTimeoutId 
set response [read -nonewline $connection]
binary scan $response H* responseReceived
regsub -all {ffff} $responseReceived "ff" responseReceived
set dataLength [format "%d" 0x[string range $responseReceived 6 7]]
set numberDataBytes [expr [expr [string length $responseReceived] - 10]/2]
puts "Data bytes, expected: $dataLength, received: $numberDataBytes"
set dataReceived [string range $responseReceived 8 [expr [string length $responseReceived] - 3]]
puts "response: $responseReceived"
set allDataReceived 1
}
proc sendcmd { cmd } {
global connection
global cmdTimeoutId
global allDataReceived
set allDataReceived 0
puts -nonewline $connection [binary format H* $cmd]
set cmdTimeoutId [after [expr 30 * 1000] handleCmdTimeout]
vwait allDataReceived
}
proc setup {} {
global connection
global cmdTimeoutId
global allDataReceived
set BBKeyIP 10.0.0.10
set BBKeyPort 2007 
if {[catch {set connection [socket $BBKeyIP $BBKeyPort]} errmsg]} {
puts "Unable to connect to BB ODB Streamer key at, $BBKeyIP:$BBKeyPort, $errmsg"
return 
}
fconfigure $connection -translation binary -blocking 0 -buffering none -encoding binary
fileevent $connection r "handleResponse $connection"
puts -nonewline $connection [binary format H* 0]
set cmdTimeoutId [after [expr 30 * 1000] handleCmdTimeout]
vwait allDataReceived
puts "Connected to OBDII Streamer"
set allDataReceived 0
}

Then write, setup, follow by the Enter Key.
You should see the following output: 

response: fffb01fffb03fffd18fffd1f
Connected to OBDII Streamer
0

If there are no error messages displayed, then enter the command,  sendcmd 0101230025 by the Enter key:

If the connection with the ODBII key is correct then, the displayed output is the current vehicle status.

Possible response are:

response: 0101a3020100a8 -> Means the ignition is on
response: 0101a3020000a8 -> Means the ignition is off

In order to get the VIN and OBDII protocol used, past the following code:

proc showkeyinfo { } {
global allDataReceived
global connection
global cmdTimeoutId
global dataReceived
#request VIN
sendcmd 010125010028
set vin ""
for {set i 2} {$i < [string length $dataReceived]} {incr i 2} {
set tmp 0x[string range $dataReceived $i [expr $i + 1]]
set vin $vin[format %c $tmp]
}
#request ODBII Protocol
sendcmd 010125010129
set obdprotocol [string range $dataReceived 2 [expr [string length $dataReceived] - 1]]
#request component versions
sendcmd 0101030005
set swVersion [format "%d.%d.%d" 0x[string range $dataReceived 0 1] 0x[string range $dataReceived 2 3] 0x[string range $dataReceived 4 5]]
set hwVersion [format "%d.%d.%d" 0x[string range $dataReceived 6 7] 0x[string range $dataReceived 8 9] 0x[string range $dataReceived 10 11]]
set dbVersion [format "%d.%d.%d" 0x[string range $dataReceived 12 13] 0x[string range $dataReceived 14 15] 0x[string range $dataReceived 16 17]]
set sysManVersion [format "%d.%d.%d" 0x[string range $dataReceived 18 19] 0x[string range $dataReceived 20 21] 0x[string range $dataReceived 22 23]]
set BootlVersion [format "%d.%d.%d" 0x[string range $dataReceived 24 25] 0x[string range $dataReceived 26 27] 0x[string range $dataReceived 28 29]]

set versions $dataReceived
puts "VIN: $vin"
puts "OBDII Protocol: $obdprotocol"
puts "Software Version: $swVersion"
puts "Hardware Version: $hwVersion"
puts "Database Version: $dbVersion"
puts "System Manager Version: $sysManVersion"
puts "Bootloader Version: $BootlVersion"
}

Then enter the command, showkeyinfo follow by enter.
The output is gonna display the VIN, OBDII protocol and the versions of the software components.

If the key is moved from another vehicle then, before you try to get the key info, you need to instruct it to re-detect the vehicle.
To do this, enter the command, sendcmd 0101240026.
You should  receive as response, 0101a400a6.
Until the key finish the detection process, its lights are gonna flash, wait until they stop flashing before you send again commands to it. 

If the response has the pattern:
0102ffXX00YY -> Means the key had replied with an error
The following XX values means a key problem:
0B = System manager image invalid. Update required
0C = FPGA image invalid. Update required
0D = Database image invalid. Update required
0F =Critical system error (reboot required)

If the response is:

0101810083 -> Means that the was not detected yet, this could happen if the key is starting up

Now enter, 

close $connection
exit 

Retrieving Information about the key

Before we run the scripts that allow you to force the key to re-detect the vehicle and get information about the key, we should disable temporarily the RuBAN heartbeat and OBDII agent.
To do this, enter the command bellow on the 819: 

conf t
no ev m p RuBAN_heartbeat_agent.tcl
no ev m p BB_ODBStreamer.tcl
end


To copy the script to the 819, enter the following commands: 

copy http://<your ruban server ip>:58000/eem/tcl/public/BB_OBDStreamerInfo.tcl flash:/RuBAN/BB_OBDStreamerInfo.tcl
copy http://<your ruban server ip>:58000/eem/tcl/public/BB_OBDStreamerRedetect.tcl flash:/RuBAN/BB_OBDStreamerRedetect.tcl
 

If you got errors when running the above commands, probably the files dont exists on your RuBAN server. 
In this case, copy the files bellow to your RuBAN server and put them in, /opt/Davra/RuBAN/tcl/public
Give the ruban user the ownership of that files, chown ruban:ruban  /opt/Davra/RuBAN/tcl/public/BB_OBDStreamerInfo.tcl and /opt/Davra/RuBAN/tcl/public/BB_OBDStreamerRedetect.tcl

After the script are on the 819, to register them enter the following commands:

conf t
ev m p BB_OBDStreamerInfo.tcl
ev m p  BB_OBDStreamerRedetect.tcl
end 
terminal monitor 

Every time you connect the key for a first time to a new vehicle, before running the info script, we need to force the key to re-detect that vehicle.
To do this, enter the following command on the 819:
 
ev m r BB_OBDStreamerRedetect.tcl 

You should see an output like the following:
Connecting to key at: 10.0.0.10:2007
Connected to OBDII Streamer
received: 0101a400a6
Key is redetecting vehicle. Wait until the lights stop to flash
Redetect vehicle done

The re-detect process takes around 30 secs, and during that time the Status light on the key is flashing.
Wait until the status light to change to always on, before running the info script. 

To retrieve the information about the key, enter the following command:

ev m r BB_OBDStreamerInfo.tcl

You should see an output like the following:

Connecting to key at: 10.0.0.10:2007
Connected to OBDII Streamer
received: 0101a512003147314a4335343434523732353233363782
received: 0101a5020103ad
received: 0101a0140001040708090c101112131415161718191a22230b

BB OBDII Sreamer Info:
VIN: 1G1JC5444R7252367
OBDII Protocol: ISO9141_2
Supported parameters: ACSystemRefrigerantMonitor CatalystMonitor ComprehensiveComponentMonitor EGRSystemMonitor EngineCoolantTemp EngineSpeed 
Get key info done

 

After finishing, in order to re-provision the 819 on RuBAN, you need to re-enable the scripts that where disable before.
To do this, enter the following commands:

conf t
ev m p RuBAN_heartbeat_agent.tcl
ev m p BB_ODBStreamer.tcl
end

Zero Touch Provisioning Configuration

Download the following file:

This is the configuration text file used on the Ruban/Zero Touch Provisioning screen. 
The file details must be updated to point to the Ruban server in use, change the <rubanIP> tags accordingly.
Also change the <rubanHttpPort> tag to the desired port value, normally this is 58000.

Open the Ruban/Zero Touch Provisioning screen and create a new ZTP profile using this configuration text file.
Take note of the value that you assign to 'Provisioning Message' as this will be needed later.

This new profile also uses a variation on the standard  'Test_Devices2.csv' file.
This one must contain the Router Serial Number found above and the IP address of the 819 unit.

Open the page ZTP - router config for full information on ZTP configuration on Ruban.

The file bellow its the B&B ODBII Streamer agent that runs on the 819.
It needs to be located on your RuBAN server on, <Ruban Server root directory>/tcl/public, and file owner and group must be set to ruban.

(Note: this file likely already resides on the Ruban server before the test was begin, but this must be clarified). 

ODBII agent configuration parameters

• loopback_ip
  The loopback ip to be used to connect to the 819 serial port.
  This parameter is mandatory. 

• revTelnetLine
  This is the Line number to use to connect to the key. 
  The default value is 7 

• bb_responseTimeout
  The timeout value, in seconds, for waiting for a response from the ODBII key.
  The default value is 5 seconds

• bb_intervalSampleTime
  The value, in seconds, for the interval sample time to requests the vehicle parameters from the key.
  This parameter is mandatory
• ignitionChangeSetJourney 
  Set to 1 to use ignition on to define an start of journey
  Note: Its also needed to have the env variable, hb_journeyStartIsSetExternally set to 1 (this controls how the heartbeat agent sets a start of a journey) 

• bb_rubanMappings_EntId 
  The value for the ENterprise ID used for the mappings from the vehicle values read from the key and the RuBAN metrics.
  The default value is 4358

• bb_requestParameters 
  The vehicle parameters names, separated by a comma, that are to be requested from the key. 
  See bellow for all possible values. 
  If not defined it defaults to: VehicleSpeed,EngineSpeed,EngineCoolantTemp,Idling
  Its possible that the vehicle where the key is connected does not support all parameters. If there is a request parameter not supported by the Vehicle then, its not reported back to ruban.
  When the agent runs, if there are not supported parameters then, a message is outputted with them.
  If this variable is set to, ALL_SUPPORTED, then all vehicle parameters supported by the key are requested 

• bb_rubanMappings 
  The mappings from the key vehicle parameters  to RuBAN metrics. If the bb_requestParameters  parameter is not the default then, this parameter is mandatory.
  The mappings are defined by a set of values, one for each entry defined on the bb_requestParameters, separated by a comma.
  Each entry could have the following format:
  <Vehicle Parameter Name>#<Metric EnterpriseId>#<Metric ElementId> or
  <Vehicle Parameter Name>#<Metric ElementId> in this case the metric enterpriseID to use is the one defined by,  bb_rubanMappings_EntId.
  Example:
  VehicleSpeed#4358#111,EngineSpeed#105
  In this example the following mappings are defined:
  1 - The VehicleSpeed key vehicle parameters is mapped to the RuBAN metric with enterpriseID=4358 and elementID=111
  2 - The EngineSpeed key vehicle parameters is mapped to the RuBAN metric with enterpriseID=<The value defined by bb_rubanMappings_EntId > the and elementID=105
  
  
• bb_metricUnits
  The units to be used when reporting the data. The possible values are:
  
  • 0 (default value) - US Units
    • Vehicle Speed: Miles per hour
    • Odometer: Miles
    • Fuel Level Remaining: US Gallons
    • Engine Coolant Temp: Fahrenheit
    • Fuel Rate: Miles Per US Gallons, US Gallons per Hour
    • Trip Odometer: Miles
    • Trip Fuel Consumption: US Gallons
       
  • 1 - International Units
    • Vehicle Speed: Kilometers per hour
    • Odometer: Kilometers 
    • Fuel Level Remaining: Liters
    • Engine Coolant Temp: Celsius
    • Fuel Rate: Liters per 100 Km, Liters per Hour
    • Trip Odometer: Kilometers 
    • Trip Fuel Consumption: Liters
    
    
  • 2 - UK Units
    • Vehicle Speed: Miles per hour
    • Odometer: Miles
    • Fuel Level Remaining: UK Gallons
    • Engine Coolant Temp: Celsius
    • Fuel Rate: Miles Per UK Gallons,  UK Gallons per Hour
    • Trip Odometer: Miles
    • Trip Fuel Consumption: UK Gallons
    
     

ODBII Key Vehicle Parameters

Verifying connectivity

Run command "show event manager policy registered" and ensure that BB_ODBStreamer.tcl.tcl and RuBAN_heartbeat_agent.tcl is contained in the output.

Ensure the red power light and the the status light are both on in the B&B ODBII Streamer key.

On the logging console on the CLI you should start to see messages appearing relating to the telematics data.

Open the Ruban/Dashboard screen and create a new dashboard containing the 'Raw Value' component.
If the connection is successful values will begin to appear for 'RPM', 'MilesPerGallon' and 'VehicleSpeedMPH'.

Troubleshooting

To activate debug info for the policy running on the router use the following commands:

conf t 
event manager environment debug_policy 1
end
 

To disable the debug info:
conf t 
event manager environment debug_policy 0
end

(items to bear in mind if connection issues occur between Ruban and the attached components)

Ensure the 819 Router is pointing to the correct Subnet and Gateway.
These settings are specific to the network the application is running on but they may be changed by typing the following:

conf t
#ip route 0.0.0.0 0.0.0.0 192.168.180.129
exit

The updated route details may be viewed by typing:

sh ip route

This this variable is set attempt to ping the Ruban server form the 819 Router to verify the connection.

Type the following to commit these changes to the router's memory:

wr mem

This means that if the router is reset these configuration changes will be retained.