ShiftX2

Introduction

(Introduction about ShiftX2)

Scripts

Disco Lights Demo

This is a test script that exercises all of the LEDs on ShiftX2. Use this as a first time test.

Script

Copy and paste this entire script into the scripting window, replacing any existing script.

function onTick()
--implement me
end

Shift Light + Twin Alert Example

(this script is a complete example that does a sequential shift light + two alert indicators)

Script

Copy and paste this entire script into the scripting window, replacing any existing script.

function onTick()
--implement me
end

Predictive Lap Timer Indicator

This script enables predictive lap time visualization.

How it works

A bar extends left or right from the center of the linear graph:

• Green bar extending to the right indicates you're beating the best time
• Orange bar extending to the left means you're falling behind.

Script

Copy and paste this entire script into the scripting window, replacing any existing script.

function onTick()
--implement me
end

Boost Gauge

This script visualizes a single analog input channel on the linear graph.

How it works

The script configures the linear graph, then reads an analog channel and updates the graph with the current value. In this case, the value represents boost level measured from a MAP sensor.

Script

Copy and paste this entire script into the scripting window, replacing any existing script.

function onTick()
--implement me
end

Only Alerts

This script enables 3 alert channels:

• Left alert for oil pressure
• Right alert for engine temperature
• Center alert for Air/Fuel ratio

How it works

The script configures the left and right alert indicators, then configures the center graph to visualize safe and dangerous AFR ranges. During operation, the analog channels for oil pressure and engine temperature are read and updates the alert indicators. The AFR channel is read and updates the linear graph.

Script

Copy and paste this entire script into the scripting window, replacing any existing script.

function onTick()
--implement me
end

ShiftX2 starter script

Use this as a starter for your own custom script

--what CAN bus ShiftX2 is connected to. 0=CAN1, 1=CAN2
sxCan=0

--primary or secondary ShiftX2 on CAN bus. 0=primary, 1=secondary
sxId=0

--brightness. 1-100% or 0 for auto brightness
sxBright=0

--tick rate in Hz. How often ShiftX2 is updated. 
tickRate=30

function sxOnUpdate()
  --Update ShiftX2 from your sensor values here
end

function sxOnBut(data)
  --add your button handler code here
  println('button: ' ..data[1])
end

--Setup ShiftX2 here
function sxOnInit()
  --add your ShiftX2 setup here
  println('ShiftX2 Init')
end

---ShiftX2 functions---
--
--Reference. Delete me to save space
--
--sxSetLinearThresh(thresholdId,segmentLength,thresholdValue,red,green,blue,flashHz)
--Setup a threshold for the linear graph
--thresholdId: Threshold ID to set. from 0-4. define in ascending order.
--segmentLength: Length of the segment when in stepped graph mode. ignored for smooth mode.
--thresholdValue: Value for this threshold.
--red: Red value (0-255)
--green: Green value (0-255)
--blue: Blue value (0-255)
--flashHz: Flash rate, in Hz; 0=no flash

--sxSetAlertThresh(alertId,thresholdId,thresholdValue,red,green,blue,flashHz)
--Setup a threshold for an alert indicator
--alertId: Id of the alert to configure
--thresholdId: Threshold ID to set. from 0-4. define in ascending order.
--thresholdValue: Value for this threshold.
--red: Red value (0-255)
--green: Green value (0-255)
--blue: Blue value (0-255)
--flashHz: Flash rate, in Hz; 0=no flash

--setAlert(alertId,red,green,blue,flashHz)
--Directly sets an alert indicator
--alertId: Alert Id to set
--red: Red value (0-255)
--green: Green value (0-255)
--blue: Blue value (0-255)
--flashHz: Flash rate, in Hz; 0=no flash

--updateAlert(alertId,currentValue)
--Updates Current alert value, using the previously configured thresholds
--alertId: Alert Id to set 
--currentValue: Updated value

--sxCfgLinearGraph(renderStyle,linearStyle,lowRange,highRange)
--Configures the linear graph
--renderStyle: 0=left->right, 1=center,2=right->left
--linearStyle: 0=smooth/interpolated, 1=stepped
--lowRange: low range of the graph
--highRange: high range of the graph (ignored if stepped linear style)

--updateLinearGraph(currentValue)
--Updates the linear graph value, using the previously configured thresholds
--currentValue: Updated value

function sxSetLinearThresh(id,s,th,r,g,b,f)
  sxTx(41,{id,s,spl(th),sph(th),r,g,b,f})
end

function sxSetAlertThresh(id,tid,th,r,g,b,f)
  sxTx(21,{id,tid,spl(th),sph(th),r,g,b,f})
end

function setBaseConfig(bright)
  sxTx(3,{bright})
end

function setAlert(id,r,g,b,f)
  sxTx(20,{id,r,g,b,f})
end

function updateAlert(id,v)
  if v~=nil then sxTx(22,{id,spl(v),sph(v)}) end
end

function sxCfgLinearGraph(rs,ls,lr,hr) 
  sxTx(40,{rs,ls,spl(lr),sph(lr),spl(hr),sph(hr)})
end

function updateLinearGraph(v)
  sxTx(42,{spl(v),sph(v)})
end

function sxInit()
  println('config shiftX2')
  setBaseConfig(sxBright)
  if sxOnInit~=nil then sxOnInit() end
end

function sxChkCan()
  id,ext,data=rxCAN(sxCan,0)
  if id==sxCanId then sxInit() end
  if id==sxCanId+60 and sxOnBut~=nil then sxOnBut(data) end
end

function sxProcess()
  sxChkCan()
  if sxOnUpdate~=nil then sxOnUpdate() end
end

function sxTx(offset, data)
  txCAN(sxCan, sxCanId + offset, 1, data)
  sleep(10)
end

function spl(v) return bit.band(v,0xFF) end
function sph(v) return bit.rshift(bit.band(v,0xFF00),8) end

function onTick()
  sxProcess()
end

sxCanId = 0xE3600 + (256 * sxId)
println('shiftx2 base id ' ..sxCanId)

setTickRate(tickRate)
sxInit()

ShiftX2 CAN bus API

Overview

The CAN bus API provides the configuration and control interface for ShiftX2.

Two styles of control are available:

• Low level control of LEDs - the ability to discretely set LED color and flash behavior
• High level control - configuring alert thresholds and linear graph up front, and then providing simple value updates

CAN Messages

CAN base ID

CAN base ID is 0xE3600 (931328)

If the device supports hardware configurable ID offsets, such as via DIP switches or breakable jumpers, each incremental offset will add 256 to the base ID.

Configuration / Runtime Options

Announcement

Broadcast by the device upon power up

CAN ID: Base + 0

Offset	What	Value
0	Total LEDs	Total number of LEDs on the device
1	Alert Indicators	Number of logical alert indicators
2	Linear Bar Graph Length	Number of LEDs in linear graph
3	Major Version	Firmware major version number
4	Minor Version	Firmware minor version number
5	Patch Version	Firmware patch version number

Reset Device

Resets the device, loading defaults

CAN ID: Base + 1

Offset	What	Value
(no data)

Statistics

Statistics information, broadcast periodically by device

CAN ID: Base + 2

Offset	What	Value
0	Major Version	Firmware major version number
1	Minor Version	Firmware minor version number
2	Patch Version	Firmware patch version number

Set Configuration Parameters Group 1

Sets various configuration options.

CAN ID: Base + 3

Offset	What	Value
0	Brightness	0 - 100; default = 0 (0=automatic brightness)
1	Automatic brightness scaling (Optional)	0-255; default=51

Set Discrete LED

A low level function to directly set any LED on the device.

CAN ID: Base + 10

Offset	What	Value
0	LED index	0 -> # of LEDs on device
1	Number of LEDs to set	0 -> # of LEDs on device (0 = set all remaining)
2	Red	0 - 255
3	Green	0 - 255
4	Blue	0 - 255
5	Flash	0-10Hz (0 = full on)

Alert Indicators

Alert Indicators are typically single LEDs or a group of LEDs treated as one logical unit. This is defined by the hardware configuration of the device.

Set Alert

Directly set an alert indicator

CAN ID: Base + 20

Offset	What	Value
0	Alert ID	0 -> # of Alert indicators
1	Red	0 - 255
2	Green	0 - 255
3	Blue	0 - 255
4	Flash	0-10Hz (0 = full on)

Set Alert Threshold

Configures an alert threshold. Up to 5 thresholds can be configured per alert indicator.

Notes:

• Threshold value must be > 0 to be valid
• Alerts are processed in descending order by Threshold ID, where:
  • The threshold is selected where the threshold is > 0 and current value is >= threshold and < than the next threshold
  • If the current value is greater than the last threshold, then the last threshold is selected.
  • If the current value is less than the first threshold, then the alert indicator is disabled.

CAN ID: Base + 21

Offset	What	Value
0	Alert ID	0 -> # of Alert indicators
1	Threshold ID	0 - 4
2	Threshold (low byte)
3	Threshold (high byte)
4	Red	0 - 255
5	Green	0 - 255
6	Blue	0 - 255
7	Flash Hz	0 - 10 (0 = full on)

Update Current Alert Value

Updates the current value for an alert indicator. The configured alert thresholds will be applied to the current value.

CAN ID: Base + 22

Offset	What	Value
0	Alert ID	0 -> # of Alert indicators
1	Value (low byte)
2	Value (high byte)

Linear Graph

The linear graph mode provides visualizations for common scenarios:

• Sequential RPM shift light where the progression is stepped
• Linear bar graph to linearly indicate a sensor value
• Center left/right graph to indicate +/- performance against a reference - such as visualizing current predictive time vs best time

Power up default configuration

Upon power up the linear graph is configured:

• Rendering style: left->right
• Linear style: stepped
• Low Range: 0
• High Range: N/A
• Threshold :
  • Threshold value: 3000 / segment length: 3 / color RGB: (0, 255, 0) / flash: 0
  • Threshold value: 5000 / segment length: 5 / color RGB: (0, 255, 255) / flash: 0
  • Threshold value: 7000 / segment length: 7 / color RGB: (255, 0, 0) / flash: 5

Configure Linear Graph

Configures the options for the linear graph portion of the device.

Rendering style:

• If left->right, linear graph illuminates left to right
• If centered, values below the mid-point in the range extend from the center to the left, and values above the mid-point extend from the center to the right.
• If right->left, linear graph illuminates right to left

Linear style:

• if smooth, graph length is updated smoothly by interpolating the current value in-between LEDs
• If stepped, creates the visual effect of stepped progressions by setting the segment length of the threshold configuration. High Range of configuration is ignored.

CAN ID: Base + 40

Offset	What	Value
0	Rendering Style	0 = left->right, 1=center, 2=right->left
1	Linear Style	0 = Smooth / interpolated, 1 = stepped
2	Low Range (low byte)
3	Low Range (high byte)
4	High Range (low byte)	(ignored if linear style = stepped)
5	High Range (high byte)	(ignored if linear style = stepped)

Set Linear Graph Threshold

Configures a linear threshold. Up to 5 thresholds can be configured

CAN ID: Base + 41

Offset	What	Value
0	Threshold ID	0 - 4
1	Segment Length	0 -> # of LEDs on device (ignored if linear style is ‘smooth’)
2	Threshold (low byte)
3	Threshold (high byte)
4	Red	0 - 255
5	Green	0 - 255
6	Blue	0 - 255
7	Flash Hz	0 - 10 (0 = full on)

Update Current Linear Graph Value

Updates the current value for the linear graph

CAN ID: Base + 42

Offset	What	Value
0	Value (low byte)
1	Value (high byte)

Notifications

Notifications related to events broadcasted from ShiftX2

Button State

Indicates a change in the button state

CAN ID: Base + 60

Offset	What	Value
0	Button state	1 = button is pressed; 0 = button