Autosport Labs - User contributions [en]

RaceCapturePro Lua Scripting

2016-10-17T01:35:04Z

Stieg: Add in `isLogging` description

=RaceCapture/Pro Scripting Guide=
==Example Scripts and How-Tos==
A large collection of example scripts can be found in our '''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==Lua Script Basics==

===Conventions===
* All inputs and outputs are numbered starting at 0 (getGpio(0), setChannel(0), etc)
* All channel values must be numbers
* All virtual channel names must have no spaces (to be fixed in future revisions)

====Writing your script====

=====onTick() function=====
Your Lua script is centered around the onTick() function. RaceCapture/Pro will periodically call this function, and here you can define your custom tasks and logic.

Example: this script will periodically write a message to the log:
<pre>
function onTick()
println("hello from RaceCapture/Pro")
end
</pre>

=====Viewing the output log=====
You can observe the loading of new script and monitor and debug the behavior of your script by using the print() / println() functions. In order to see the log output, enable the "Poll Log" checkbox in the scripting window:

[[image:Hello_RaceCapturePro_script.png|800px]]

=====Controlling the onTick() rate====
You can control how fast your script is executed using the setTickRate() function. The tick Rate is specified in Hz, and the default rate is 1Hz.

<pre>
count = 0
setTickRate(10)

function onTick()
count = count + 1
println("Tick: " ..count)
end
</pre>

[[image:RaceCapture_tick_count.png|800px]]

=====Reading and controlling inputs and outputs=====

The Lua scripting enables endless combinations of custom behaviors by reading sensor values, controlling output lines, broadcasting CAN messages and writing data to the Auxiliary serial port.

Example: Reading a sensor value and activating an output based on a threshold.

Given:
* A calibrated temperature sensor is connected to the first analog input (0);
* The first GPIO is configured for output mode

This script will activate the output upon crossing the temperature threshold of 212.

<pre>
function onTick()
temperature = getAnalog(0)
if temperature > 212 then
setGpio(0, 1)
else
setGpio(0, 0)
end
end
</pre>
=====Combining multiple functions=====
When combining multiple functions into one script, it's recommended to break them into multiple functions and reference them from the main onTick() function.

Example:

<pre>
function checkTemps()

[ temperature checking logic goes here ]

end

function checkAutoLogging()

[ automatic logging logic goes here ]

end

function onTick()
checkTemps()
checkAutoLogging()
end
</pre>

=====Debugging your script=====
If you're not sure why your script is misbehaving, you can use the println() function to output messages in the log and observe how your script is behaving.

Example:

<pre>
function onTick()
temperature = getAnalog(0)
println("current temp: " ..temperature)
if temperature > 212 then
println("over temp!")
setGpio(0, 1)
else
println("under temp")
setGpio(0, 0)
end
end
</pre>

=====Lua Reference=====
RaceCapture/Pro uses the standard, lightweight Lua scripting language used as an extension / customization language for many software applications and especially gaming.

* See [https://www.lua.org/ lua.org] for additional information on how to use the Lua language
=====More examples=====
You can see more examples in our [[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]] section.

=API Reference=

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2
** state: (int / ''(since 2.10.0)'' bool) 1 / true = output active; 0 / false = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getGpsAltitude()===
Provides the current GPS calculated altitude from sea level in feet. The method will return 0 if there is no GPS lock.
* Added: v2.9.0
* Parameters: ''None''
* Returns: <altitude>

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms. For non-blocking functionality specify a timeout of 0.
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter and mask ID, to ignore CAN messages that match a particular ID pattern.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

* '''Note''' - you should only define one onTick() function in your code. If multiple onTick() functions are defined, only the last defined onTick() function will be used.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===isLogging()===
Tells the caller if a logging session is in progress
* params
** (none)
* returns
** 0 if not logging, non zero otherwise.

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state: (int / ''[as of 2.10.0]'' bool) 1 / true = on, 0 / false = off
* returns
** (none)

===setBgStream( on/off )===
Sets the state of background streaming
* params
** Boolean: true for on, false for off.
* returns
** (none)

===getBgStream()===
Gets the state of background streaming
* params
** (none)
* returns
** Boolean: True for on, false for off.

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 100 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===getChannel( <Channel ID | Channel Name> )===
* Available: v2.9.0
* Parameters
** Channel ID (number) - The channel id value as provided by the ''addChannel'' method.
** Channel Name (string) - The name of the channel as provided to the ''addChannel'' method. Using the Channel ID method is preferred and is faster.
* Returns
** (number) The value of the channel.
* Examples:
** <code> val = getChannel(1) </code>
** <code> val = getChannel("foo") </code>

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

RaceCapture-Pro MK2

2016-07-24T21:14:44Z

Stieg: Remove Magnetometer availability until we actually add support for it.

=RaceCapture/Pro Quick Links=
* [[Image:add_to_cart.png|link=http://www.autosportlabs.com/product/racecapturepro/]]

==Getting Started==
*'''[[RaceCapturePro2_QuickStart|First time setup]]'''
*'''[[RaceCapturePro_Downloads|Software Downloads]]'''
*'''[[RaceCapturePro2_Hardware_Install|Hardware install]]'''

==User Guides==
*[[RCP_CAN|CAN bus / ECU integration guide]]
*[[RaceCapturePro2_hardware_guide|Hardware installation and operation guide]]
*[[RaceCapturePro2_3.5G_module_upgrade|3.5G Module Upgrade guide]]
*[[RaceCapture_App_User%27s_Guide|RaceCapture App User's guide]]
*[[RaceCapturePro_Sensors|Sensor guide]]
*[[RaceCapturePro_Lua_Scripting|Lua scripting guide]]

==Accessory / add-on guides ==
*[[SensorX|SensorX sensor breakout board assembly guide]]
*[[CoilX|CoilX Tach interface to ignition coils guide]]
*[[RaceCapturePro2_GoProWiFi|WiFi module for automatic GoPro control guide]]

==How To==
*[[RaceCapturePro2_TelemetryQuickstart|How to: set up telemetry]]
*[[RaceCapturePro2_Enable_Predictive_Timing|How to: enable Predictive Timing]]
*[[RaceCapturePro2_OBD2|How to: enable OBD2 channels]]
*[[RaceCapturePro2_Calibrate_Sensor|How to: calibrate and configure an analog sensor]]
*[[RaceCapturePro2_ShiftLights|How to: sequential shift lights]]
*[[RaceCapturePro2_GPS|How to: get best GPS data]]
*[[RaceTracks|How to: Submit a new race track]]
*[[RaceCapturePro_Analysis|How to: analyze your data]]
*[[RaceCapturePro_FAQ|More FAQs and How-To's]]

==By Car==
*[[RaceCapturePro2_vehicle_guide|Vehicle Guide]]

==By Sensor Type==
*[[RaceCapturePro2_RPM|RPM]]'''

==Reference==
*[[RaceCapturePro2_logfile_reference|Log file reference]]

==More Information==
*[https://github.com/autosportlabs Source code]

===Previous Hardware Versions===
[[RaceCapturePro-MK1|RaceCapture/Pro MK1]]

=Quick Reference=
Download a [http://www.autosportlabs.com/racecapturepro-mk2-quick-reference/racecapture-pro-mk2-quick-reference-sheet printable PDF]

[[Image:RaceCapture-Pro MK2 quick reference sheet.jpg]]

=RaceCapture/Pro MK2 Specifications=

{| class="wikitable" style="text-align: left"
!colspan="2"|Input / Output Channels
|-
!colspan="2"|'''Analog Inputs'''
|-
|Channels
|8 (battery voltage dedicated on channel 8)
|-
|Voltage range
|0-5v
|-
|Input impedance
|1M ohm
|-
|Voltage protection
|400v (intermittent)
|-
|ADC precision
|12 bit
|-
|Maximum sample rate
|1000Hz
|-
|Mapping
|Raw / Linear formula / Interpolated map
|-
!colspan="2"|'''Digital I/O'''
|-
|Channels
|3
|-
|Output mode type
|Open drain
|-
|Output current capacity
|1A, inductive clamped
|-
|Input mode voltage range
|0-12v
|-
|Input voltage protection
|400v (intermittent)
|-
|Maximum sample rate
|1000Hz
|-
!colspan="2"|'''Timer Inputs (RPM / Frequency)'''
|-
|Channels
|3
|-
|Input voltage protection
|400v (intermittent)
|-
|Maximum sample rate
|1000Hz
|-
!colspan="2"|'''PWM/Analog outputs'''
|-
|Channels
|4
|-
|PWM output type
|push/pull
|-
|PWM output voltage range
|5v
|-
|Output current capacity
|50mA
|-
|Analog Output
|0-5v
|-
!colspan="2"|Voltage Reference
|-
|Output Voltage/Capacity
|5v / 1A
|-
!colspan="2"|Connectivity
|-
!colspan="2"|'''CAN Bus'''
|-
|CAN Channels
|2
|-
|CAN baud rate
|125K, 250K, 500K, 1M baud
|-
|CAN filters
|14 per channel
|-
|Protocol support
|OBDII PID, custom CAN messaging
|-
!colspan="2"|'''Telemetry/Wireless'''
|-
|Cellular (North America)
|3.5G GSM 850/1900MHz (internal module, optional)
|-
|Cellular (Worldwide)
|2.5G Quad-band GSM (internal module, optional)
|-
|Bluetooth
|Bluetooth 2.0 (external module, optional)
|-
|Aux Serial
|Type External RJ11 / RS232 signaling
|-
|Max Baud Rate
|230400
|-
!colspan="2"|Inertial Motion Unit
|-
|Accelerometer Channels
|3 (X/Y/Z) (2G, 4G capable)
|-
|Gyro
|3 (Yaw/Pitch/Roll) (1000 degrees/sec)
|-
|GPS Type
|External active antenna
|-
|GPS Maximum sample rate
|50Hz
|-
|GPS accuracy
|2.5M CEP
|-
!colspan="2"|Storage
|-
|Micro SD
|Up to 32GB (SDHC) FAT32
|-
!colspan="2"|Configuration Capacity
|-
|Auto-detect track database
|240
|-
|Sectors per track
|20
|-
|Channel support
|200
|-
!colspan="2"|Physical
|-
|Dimensions
|5.3" (width) x 4.2" (height) x 1.2" (tall) / 135x110x31 mm(est)
|-
|Mounting area
|5.5"(140mm) x 4"(102mm)
|-
|Mounting holes
|Dual mounting points on 5" (127mm) centers - 0.125"-0.25" (3-6mm) fastener
|-
|Weight
|9oz / 255gm (est)
|-
|Power connection
|Terminal block: 1A max RJ45: 1A max
|-
|Power Consumption (max)
|Main System: 0.6W With Bluetooth: 1.6W With Cellular Telemetry: 8.6W With Cellular Telemetry and Bluetooth: 9.6W
|-
|Temperature
| Max Internal Temperature while operating: -40°C ~ 85°C / -40°C ~ 80°C (Telemetry module)
|}

[[Image:add_to_cart.png|link=http://www.autosportlabs.com/product/racecapturepro/]]

RaceCapturePro Lua Scripting

2016-07-10T04:24:36Z

Stieg: /* setLed( led, state ) */

=RaceCapture/Pro Scripting Guide=
==Example Scripts and How-Tos==
A large collection of example scripts can be found in our '''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==Lua Script Basics==

===Conventions===
* All inputs and outputs are numbered starting at 0 (getGpio(0), setChannel(0), etc)
* All channel values must be numbers
* All virtual channel names must have no spaces (to be fixed in future revisions)

====Writing your script====

=====onTick() function=====
Your Lua script is centered around the onTick() function. RaceCapture/Pro will periodically call this function, and here you can define your custom tasks and logic.

Example: this script will periodically write a message to the log:
<pre>
function onTick()
println("hello from RaceCapture/Pro")
end
</pre>

=====Viewing the output log=====
You can observe the loading of new script and monitor and debug the behavior of your script by using the print() / println() functions. In order to see the log output, enable the "Poll Log" checkbox in the scripting window:

[[image:Hello_RaceCapturePro_script.png|800px]]

=====Controlling the onTick() rate====
You can control how fast your script is executed using the setTickRate() function. The tick Rate is specified in Hz, and the default rate is 1Hz.

<pre>
count = 0
setTickRate(10)

function onTick()
count = count + 1
println("Tick: " ..count)
end
</pre>

[[image:RaceCapture_tick_count.png|800px]]

=====Reading and controlling inputs and outputs=====

The Lua scripting enables endless combinations of custom behaviors by reading sensor values, controlling output lines, broadcasting CAN messages and writing data to the Auxiliary serial port.

Example: Reading a sensor value and activating an output based on a threshold.

Given:
* A calibrated temperature sensor is connected to the first analog input (0);
* The first GPIO is configured for output mode

This script will activate the output upon crossing the temperature threshold of 212.

<pre>
function onTick()
temperature = getAnalog(0)
if temperature > 212 then
setGpio(0, 1)
else
setGpio(0, 0)
end
end
</pre>
=====Combining multiple functions=====
When combining multiple functions into one script, it's recommended to break them into multiple functions and reference them from the main onTick() function.

Example:

<pre>
function checkTemps()

[ temperature checking logic goes here ]

end

function checkAutoLogging()

[ automatic logging logic goes here ]

end

function onTick()
checkTemps()
checkAutoLogging()
end
</pre>

=====Debugging your script=====
If you're not sure why your script is misbehaving, you can use the println() function to output messages in the log and observe how your script is behaving.

Example:

<pre>
function onTick()
temperature = getAnalog(0)
println("current temp: " ..temperature)
if temperature > 212 then
println("over temp!")
setGpio(0, 1)
else
println("under temp")
setGpio(0, 0)
end
end
</pre>

=====Lua Reference=====
RaceCapture/Pro uses the standard, lightweight Lua scripting language used as an extension / customization language for many software applications and especially gaming.

* See [https://www.lua.org/ lua.org] for additional information on how to use the Lua language
=====More examples=====
You can see more examples in our [[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]] section.

=API Reference=

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2
** state: (int / ''(since 2.10.0)'' bool) 1 / true = output active; 0 / false = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getGpsAltitude()===
Provides the current GPS calculated altitude from sea level in feet. The method will return 0 if there is no GPS lock.
* Added: v2.9.0
* Parameters: ''None''
* Returns: <altitude>

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms. For non-blocking functionality specify a timeout of 0.
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

* '''Note''' - you should only define one onTick() function in your code. If multiple onTick() functions are defined, only the last defined onTick() function will be used.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state: (int / ''[as of 2.10.0]'' bool) 1 / true = on, 0 / false = off
* returns
** (none)

===setBgStream( on/off )===
Sets the state of background streaming
* params
** Boolean: true for on, false for off.
* returns
** (none)

===getBgStream()===
Gets the state of background streaming
* params
** (none)
* returns
** Boolean: True for on, false for off.

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===getChannel( <Channel ID | Channel Name> )===
* Available: v2.9.0
* Parameters
** Channel ID (number) - The channel id value as provided by the ''addChannel'' method.
** Channel Name (string) - The name of the channel as provided to the ''addChannel'' method. Using the Channel ID method is preferred and is faster.
* Returns
** (number) The value of the channel.
* Examples:
** <code> val = getChannel(1) </code>
** <code> val = getChannel("foo") </code>

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

RaceCapturePro Lua Scripting

2016-07-10T02:37:48Z

Stieg: Add note about bool and cleanup a bit.

=RaceCapture/Pro Scripting Guide=
==Example Scripts and How-Tos==
A large collection of example scripts can be found in our '''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==Lua Script Basics==

===Conventions===
* All inputs and outputs are numbered starting at 0 (getGpio(0), setChannel(0), etc)
* All channel values must be numbers
* All virtual channel names must have no spaces (to be fixed in future revisions)

====Writing your script====

=====onTick() function=====
Your Lua script is centered around the onTick() function. RaceCapture/Pro will periodically call this function, and here you can define your custom tasks and logic.

Example: this script will periodically write a message to the log:
<pre>
function onTick()
println("hello from RaceCapture/Pro")
end
</pre>

=====Viewing the output log=====
You can observe the loading of new script and monitor and debug the behavior of your script by using the print() / println() functions. In order to see the log output, enable the "Poll Log" checkbox in the scripting window:

[[image:Hello_RaceCapturePro_script.png|800px]]

=====Controlling the onTick() rate====
You can control how fast your script is executed using the setTickRate() function. The tick Rate is specified in Hz, and the default rate is 1Hz.

<pre>
count = 0
setTickRate(10)

function onTick()
count = count + 1
println("Tick: " ..count)
end
</pre>

[[image:RaceCapture_tick_count.png|800px]]

=====Reading and controlling inputs and outputs=====

The Lua scripting enables endless combinations of custom behaviors by reading sensor values, controlling output lines, broadcasting CAN messages and writing data to the Auxiliary serial port.

Example: Reading a sensor value and activating an output based on a threshold.

Given:
* A calibrated temperature sensor is connected to the first analog input (0);
* The first GPIO is configured for output mode

This script will activate the output upon crossing the temperature threshold of 212.

<pre>
function onTick()
temperature = getAnalog(0)
if temperature > 212 then
setGpio(0, 1)
else
setGpio(0, 0)
end
end
</pre>
=====Combining multiple functions=====
When combining multiple functions into one script, it's recommended to break them into multiple functions and reference them from the main onTick() function.

Example:

<pre>
function checkTemps()

[ temperature checking logic goes here ]

end

function checkAutoLogging()

[ automatic logging logic goes here ]

end

function onTick()
checkTemps()
checkAutoLogging()
end
</pre>

=====Debugging your script=====
If you're not sure why your script is misbehaving, you can use the println() function to output messages in the log and observe how your script is behaving.

Example:

<pre>
function onTick()
temperature = getAnalog(0)
println("current temp: " ..temperature)
if temperature > 212 then
println("over temp!")
setGpio(0, 1)
else
println("under temp")
setGpio(0, 0)
end
end
</pre>

=====Lua Reference=====
RaceCapture/Pro uses the standard, lightweight Lua scripting language used as an extension / customization language for many software applications and especially gaming.

* See [https://www.lua.org/ lua.org] for additional information on how to use the Lua language
=====More examples=====
You can see more examples in our [[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]] section.

=API Reference=

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2
** state: (int / ''(since 2.10.0)'' bool) 1 / true = output active; 0 / false = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getGpsAltitude()===
Provides the current GPS calculated altitude from sea level in feet. The method will return 0 if there is no GPS lock.
* Added: v2.9.0
* Parameters: ''None''
* Returns: <altitude>

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms. For non-blocking functionality specify a timeout of 0.
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

* '''Note''' - you should only define one onTick() function in your code. If multiple onTick() functions are defined, only the last defined onTick() function will be used.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state : 1 = on, 0 = off
* returns
** (none)

===setBgStream( on/off )===
Sets the state of background streaming
* params
** Boolean: true for on, false for off.
* returns
** (none)

===getBgStream()===
Gets the state of background streaming
* params
** (none)
* returns
** Boolean: True for on, false for off.

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===getChannel( <Channel ID | Channel Name> )===
* Available: v2.9.0
* Parameters
** Channel ID (number) - The channel id value as provided by the ''addChannel'' method.
** Channel Name (string) - The name of the channel as provided to the ''addChannel'' method. Using the Channel ID method is preferred and is faster.
* Returns
** (number) The value of the channel.
* Examples:
** <code> val = getChannel(1) </code>
** <code> val = getChannel("foo") </code>

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

RaceTracks

2016-06-16T16:49:21Z

Stieg: /* Record Basic Track Info */

__NOTOC__

=How to create / submit a track map=

==Pick a Track==
Pick a track map below that isn't completed.

==Open Up a Basic Text Editor==
You will need a basic text editor to copy and past information into. Applications like Notepad, Textedit, Gedit all work very well.

== Open Up The Drawing Tool ==
Use this handy [http://www.birdtheme.org/useful/v3tool.html Map Drawing tool] to create an outline of the race track as well as find GeoPoints. I will assume you are using it throughout the rest of this tutorial.

== Record Basic Track Info==
We need a few basic things to get going. They are as follows:
*Track Name
*Track Configuration
*Country Track is Located In
*Center area of track (We use this for zooming and display purposes).
*Start/Finish GeoPoint on track.

Add all that information into your text editor.

==Draw the Track==
Now its time to draw the outline of the track. Clear the tool above using the "Clear Map" button and do the following:

# Find the race track track using the search bar and zoom in on the track.
# Locate the start / finish line and make that your first point by clicking it.
# Follow the contour of the track by clicking around the track, making sure your lines are '''in the centerline of the track''' (This is really important).
# If you make a mistake, you can undo points by clicking the "Delete Last Point" button.

When you are finished, copy the text blob from the tool into the text editor. Label the blob as "Outline"

''Tips:''
* Zoom all the way in on the map to get the best placement accuracy
* Make more points in curves so it looks smooth.
* Draw the lines using the centerline of the track.

==Record Sector Points ''(Optional)''==
If you want to go the extra mile and be extra awesome, you can include sector points. These are points that allow us to partition
the track into sections so we can get timing info for individual sections of the track. However there is a catch, we can only support up to 20 sector points per track (not including start/finish). To add sector data, do the following:

#Use the same tool. Before you start, clear out any data by selecting the "Clear Map" button.
#Think about how you would logically divide the track in your mind. What corners or sections are most important to you?
#With that in mind, select these points. Don't worry about the shape you draw, we are interested in the points.
#* REMEMBER: You can only have up to 20 points. DO NOT include start finish as one of these points.

When you are finished, copy the text blob from the tool into the text editor. Label the blob as "Sectors"

==Submit It!==
When you've gotten all the data described above, copy and paste all of the text from your text editor into an email and [mailto:racecapture@autosportlabs.com submit it to us]. Be sure you included the basic track data! We will review the track data and if sufficient, incorporate it into our Mobile app and online!

'''Thank you from the Autosport Labs team!'''

=Tracks=
To see a list of track maps we have in our database, visit this page: http://race-capture.com/venues

Cellular

2016-06-08T18:56:07Z

Stieg: /* SARA-U280 */

= Cellular Technoligies and RaceCapture/Pro =

This page covers the equipment and technoligies used in RaceCapture/Pro telemetry implementations. It discusses the supported bands & frequencies and lists the technologies used. It also covers cellular providers in priority order based on country. This is still a work in progress... we would love to hear from users about providers in their local country.

= 2.5G =
== SIM900 ==
The original telemetry on MK1 and MK2 is a 2G module made by SIMCOM. This is a GPRS device with a good range but limited bandwidth and near universal worldwide coverage. Specs are as follows:

* Frequencies (Bands) : 850 (5) / 900 (8) / 1800 (3) / 1900 (2) MHz
* Protocols: GPRS multi-slot class 10/8
** Class 4 (2 W @850/ 900 MHz)
** Class 1 (1 W @ 1800/1900MHz)
* Max Upload Speed: 21.4 kb/s

==== Links ====
* http://www.propox.com/download/docs/SIM900.pdf
* https://en.wikipedia.org/wiki/General_Packet_Radio_Service

= 3.5G =
This is the latest in supported telemetry chips for RaceCapture/Pro. This unit is vastly improved compared to its predecessor, but some models can be limited by only supporting a smaller number of frequencies compared to the SIM900. Initially RaceCapture/Pro will support the SARA-U280. We intend to introduce other models in the future.

== SARA-U280 ==
This is the initial 3G chip available for RaceCapture/Pro units in North America (USA, Canada and Mexico). Its specs are as follows:

* Frequencies: 850 MHz / 1900 MHz
* Protocols: UMTS/HSPA (HSDPA/HSUPA)
* Max Upload Speed: 5.76 Mb/s

==== Links ====
* https://www.u-blox.com/en/product/sara-u2-series

== SARA-U270 ==
This is a 3G chip we are testing for enabling 3G support worldwide. Its specs are as follows:

* Frequencies: 900 MHz / 2100 MHz
* Protocols: UMTS/HSPA (HSDPA/HSUPA)
* Max Upload Speed: 5.76 Mb/s

==== Links ====
* https://www.u-blox.com/en/product/sara-u2-series

= Cellular Providers =
This section convers the basics about cellular providers in various countries. Specifically it lists what bands they are known to support. This is so you can best match up your device with a cellular provider. Providers are listed in descending order, with the ones at the top being prefered.

== USA ==
=== AT&T ===
AT&T is the group we have had the best experience with in the states. Primarily its because they support all the bands that both our 2G and 3G devices support and they tend to have the best coverage. However, working with them directly can be a pain. We often suggest using an Mobile Virtual Network Operator (MVNO) that makes use of the AT&T infrastructure. That way you can avoid the hassle of AT&T and still get the same great coverage. One common MVNO we recommend is Straight Talk.

==== Frequencies (Bands) and Protocols ====
* 850 MHz (5)
** GPRS (This will be discontinued in 2017)
** UMTS
** HSPA
** HSPA+
* 1900 MHz (2)
** GPRS (This will be discontinued in 2017)
** UMTS
** HSPA
** HSPA+

==== Links ====
* https://en.wikipedia.org/wiki/AT%26T_Mobility

=== T-Mobile ===
T-Mobile is the other mobile data provider in the states that you can use with RaceCapture/Pro Telemetry. While T-Mobile is often cheaper than AT&T, their coverage tends to not always be as good in remote areas where race tracks tend to live. They also don't support all the bands that the RaceCapture/Pro can use. Because of this, we tend to avoid them unless they are known to be good at a particular location.

==== Frequencies (Bands) and Protocols ====
* 1900 MHz (2)
** GPRS (This will be discontinued in 2017)
** UMTS
** HSPA
** HSPA+
* 1700/2100 MHz (4) - NOTE: This is being phased out and "re-farmed" to the 1900 MHz spectrum
** UMTS
** HSPA
** HSPA+

==== Links ====
* https://en.wikipedia.org/wiki/T-Mobile_US

RaceCapturePro Lua Scripting

2016-05-02T04:05:50Z

Stieg: Add note about non-blocking functionality.

==Example Scripts and How-Tos==

'''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==Lua Script Basics==

* All inputs and outputs are numbered starting at 0 (getGpio(0), setChannel(0), etc)
* All channel values must be numbers
* All virtual channel names must have no spaces (to be fixed in future revisions)

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2, state - 1 = output active; 0 = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getGpsAltitude()===
Provides the current GPS calculated altitude from sea level in feet. The method will return 0 if there is no GPS lock.
* Added: v2.9.0
* Parameters: ''None''
* Returns: <altitude>

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms. For non-blocking functionality specify a timeout of 0.
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

* '''Note''' - you should only define one onTick() function in your code. If multiple onTick() functions are defined, only the last defined onTick() function will be used.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state : 1 = on, 0 = off
* returns
** (none)

===setBgStream( on/off )===
Sets the state of background streaming
* params
** Boolean: true for on, false for off.
* returns
** (none)

===getBgStream()===
Gets the state of background streaming
* params
** (none)
* returns
** Boolean: True for on, false for off.

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===getChannel( <Channel ID | Channel Name> )===
* Available: v2.9.0
* Parameters
** Channel ID (number) - The channel id value as provided by the ''addChannel'' method.
** Channel Name (string) - The name of the channel as provided to the ''addChannel'' method. Using the Channel ID method is preferred and is faster.
* Returns
** (number) The value of the channel.
* Examples:
** <code> val = getChannel(1) </code>
** <code> val = getChannel("foo") </code>

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

Tablets/Android/Samsung-SM-T320

2016-04-28T02:34:38Z

Stieg: Created page with "Known otherwise as the Samsung Galaxy Tab Pro 8.4, == Overivew == * Status: Verified by ASL * Last Tested: 2016-04-27 ** Tested by: Stieg ** App Version: 1.5.2 ** Firmware Ve..."

Known otherwise as the Samsung Galaxy Tab Pro 8.4,

== Overivew ==
* Status: Verified by ASL
* Last Tested: 2016-04-27
** Tested by: Stieg
** App Version: 1.5.2
** Firmware Version: 1.9.0

== Screen ==
Reasonably bright screen. Does well during the daylight. Not super good in direct sunlight.

== Bluetooth ==
Works reasonably well. No major hiccups. Sometimes need to restart the Bluetooth stack to get it to recognize RaceCapture.

== Cellular Support ==
None.

== Holders & Charger ==
I use a RAM mount to hold this tablet in Lemons. Use the 2A charger sold in the ASL store. Works very well.

Tablets/FireOS

2016-04-28T02:11:01Z

Stieg: Created page with "FireOS is Amazon's Android-based mobile operating system."

FireOS is Amazon's Android-based mobile operating system.

Tablets/iOS

2016-04-28T02:05:46Z

Stieg: Created page with "iOS support for the RaceCapture App is still a work in progress. When its officially released we will begin adding tablet information here."

iOS support for the RaceCapture App is still a work in progress. When its officially released we will begin adding tablet information here.

Tablets/Android

2016-04-28T02:03:54Z

Stieg: Created page with "This page and its sub pages contain all information about Android tablets that we support. ''NOTE: Fire tablets are in their own section as they are not quite in the same eco..."

This page and its sub pages contain all information about Android tablets that we support. ''NOTE: Fire tablets are in their own section as they are not quite in the same ecosystem as Android''

== Minimum Requirements ==
* Android 4.4 (KitKat) and higher
* Quad core 1.6 GHz processor
* 2 GB RAM
* 8 GB Storage
* 1024x600 or greater resolution

RaceCapturePro Lua Scripting

2016-04-16T17:09:56Z

Stieg: /* Logger Control Functions */

==Example Scripts and How-Tos==

'''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==Lua Script Basics==

* All inputs and outputs are numbered starting at 0 (getGpio(0), setChannel(0), etc)
* All channel values must be numbers
* All virtual channel names must have no spaces (to be fixed in future revisions)

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2, state - 1 = output active; 0 = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getGpsAltitude()===
Provides the current GPS calculated altitude from sea level in feet. The method will return 0 if there is no GPS lock.
* Added: v2.9.0
* Parameters: ''None''
* Returns: <altitude>

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

* '''Note''' - you should only define one onTick() function in your code. If multiple onTick() functions are defined, only the last defined onTick() function will be used.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state : 1 = on, 0 = off
* returns
** (none)

===setBgStream( on/off )===
Sets the state of background streaming
* params
** Boolean: true for on, false for off.
* returns
** (none)

===getBgStream()===
Gets the state of background streaming
* params
** (none)
* returns
** Boolean: True for on, false for off.

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===getChannel( <Channel ID | Channel Name> )===
* Available: v2.9.0
* Parameters
** Channel ID (number) - The channel id value as provided by the ''addChannel'' method.
** Channel Name (string) - The name of the channel as provided to the ''addChannel'' method. Using the Channel ID method is preferred and is faster.
* Returns
** (number) The value of the channel.
* Examples:
** <code> val = getChannel(1) </code>
** <code> val = getChannel("foo") </code>

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

Cellular

2016-04-07T03:41:22Z

Stieg: Created page with " = Cellular Technoligies and RaceCapture/Pro = This page covers the equipment and technoligies used in RaceCapture/Pro telemetry implementations. It discusses the supported..."

= Cellular Technoligies and RaceCapture/Pro =

This page covers the equipment and technoligies used in RaceCapture/Pro telemetry implementations. It discusses the supported bands & frequencies and lists the technologies used. It also covers cellular providers in priority order based on country. This is still a work in progress... we would love to hear from users about providers in their local country.

= 2G =
== SIM900 ==
The original telemetry on MK1 and MK2 is a 2G module made by SIMCOM. This is a GPRS device with a good range but limited bandwidth. Specs are as follows:

* Frequencies (Bands) : 850 (5) / 900 (8) / 1800 (3) / 1900 (2) MHz
* Protocols: GPRS multi-slot class 10/8
** Class 4 (2 W @850/ 900 MHz)
** Class 1 (1 W @ 1800/1900MHz)
* Max Upload Speed: 21.4 kb/s

==== Links ====
* http://www.propox.com/download/docs/SIM900.pdf
* https://en.wikipedia.org/wiki/General_Packet_Radio_Service

= 3G =
This is the latest in supported telemetry chips for RaceCapture/Pro. This unit is vastly improved compared to its predecessor, but some models can be limited by only supporting a smaller number of frequencies compared to the SIM900. Initially RaceCapture/Pro will support the SARA-U280. We intend to introduce other models in the future.

== SARA-U280 ==
This is the initial 3G chip available for RaceCapture/Pro units in the USA. Its specs are as follows:

* Frequencies (Band): 850 (5) / 1900 (2) MHz
* Protocols: UMTS/HSPA
* Max Upload Speed: 5.76 Mb/s

==== Links ====
* https://www.u-blox.com/en/product/sara-u2-series
= Cellular Providers =
This section convers the basics about cellular providers in various countries. Specifically it lists what bands they are known to support. This is so you can best match up your device with a cellular provider. Providers are listed in descending order, with the ones at the top being prefered.

== USA ==
=== AT&T ===
AT&T is the group we have had the best experience with in the states. Primarily its because they support all the bands that both our 2G and 3G devices support and they tend to have the best coverage. However, working with them directly can be a pain. We often suggest using an Mobile Virtual Network Operator (MVNO) that makes use of the AT&T infrastructure. That way you can avoid the hassle of AT&T and still get the same great coverage. One common MVNO we recommend is Straight Talk.

==== Frequencies (Bands) and Protocols ====
* 850 MHz (5)
** GPRS (This will be discontinued in 2017)
** UMTS
** HSPA
** HSPA+
* 1900 MHz (2)
** GPRS (This will be discontinued in 2017)
** UMTS
** HSPA
** HSPA+

==== Links ====
* https://en.wikipedia.org/wiki/AT%26T_Mobility

=== T-Mobile ===
T-Mobile is the other mobile data provider in the states that you can use with RaceCapture/Pro Telemetry. While T-Mobile is often cheaper than AT&T, their coverage tends to not always be as good in remote areas where race tracks tend to live. They also don't support all the bands that the RaceCapture/Pro can use. Because of this, we tend to avoid them unless they are known to be good at a particular location.

==== Frequencies (Bands) and Protocols ====
* 1900 MHz (2)
** GPRS (This will be discontinued in 2017)
** UMTS
** HSPA
** HSPA+
* 1700/2100 MHz (4) - NOTE: This is being phased out and "re-farmed" to the 1900 MHz spectrum
** UMTS
** HSPA
** HSPA+

==== Links ====
* https://en.wikipedia.org/wiki/T-Mobile_US

RaceCapturePro Lua Scripting

2016-03-07T02:36:00Z

Stieg: Add the getChannel method

==Example Scripts and How-Tos==

'''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2, state - 1 = output active; 0 = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getGpsAltitude()===
Provides the current GPS calculated altitude from sea level in feet. The method will return 0 if there is no GPS lock.
* Added: v2.9.0
* Parameters: ''None''
* Returns: <altitude>

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

* '''Note''' - you should only define one onTick() function in your code. If multiple onTick() functions are defined, only the last defined onTick() function will be used.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state : 1 = on, 0 = off
* returns
** (none)

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===getChannel( <Channel ID | Channel Name> )===
* Available: v2.9.0
* Parameters
** Channel ID (number) - The channel id value as provided by the ''addChannel'' method.
** Channel Name (string) - The name of the channel as provided to the ''addChannel'' method. Using the Channel ID method is preferred and is faster.
* Returns
** (number) The value of the channel.
* Examples:
** <code> val = getChannel(1) </code>
** <code> val = getChannel("foo") </code>

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

RaceCapturePro Lua Scripting

2016-03-07T02:20:03Z

Stieg: /* GPS Sensor Functions */

==Example Scripts and How-Tos==

'''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2, state - 1 = output active; 0 = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getGpsAltitude()===
Provides the current GPS calculated altitude from sea level in feet. The method will return 0 if there is no GPS lock.
* Added: v2.9.0
* Parameters: ''None''
* Returns: <altitude>

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

* '''Note''' - you should only define one onTick() function in your code. If multiple onTick() functions are defined, only the last defined onTick() function will be used.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state : 1 = on, 0 = off
* returns
** (none)

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

RaceCapturePro Lua Scripting

2016-03-07T02:16:55Z

Stieg: Add getGpsAltitude

==Example Scripts and How-Tos==

'''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2, state - 1 = output active; 0 = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getGpsAltitude()===
Provides the current GPS calculated altitude from sea level in feet.
* params
** (none)
* returns
** Feet above sea level.

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

* '''Note''' - you should only define one onTick() function in your code. If multiple onTick() functions are defined, only the last defined onTick() function will be used.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state : 1 = on, 0 = off
* returns
** (none)

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

RaceCapturePro Lua Scripting

2016-02-15T21:02:31Z

Stieg: Add dutyCyclePct param description.

==Example Scripts and How-Tos==

'''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2, state - 1 = output active; 0 = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
** dutyCyclePct: Percentage value of the duty cycle as a counting number 0 - 100
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state : 1 = on, 0 = off
* returns
** (none)

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port, [timeout])===
''Available since firmware 2.8.4'' 
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port, [timeout])===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
''Available since firmware 2.8.4'' 
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available since firmware 2.8.4'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available since firmware 2.8.4'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond

RaceCapturePro2 Hardware Install

2016-01-21T05:11:30Z

Stieg: Improved the installation section.

==Connections==

[[Image:RaceCapture-Pro MK2 quick reference sheet.jpg]]

===Power Connection===
Connect RaceCapture/Pro to a power source between 9 and 24V. To fully support all devices and outputs, provide at least a 5A fused connection.

==Sensors==
'''Also see the [[RaceCapturePro_Sensors|Comprehensive Sensor installation guide]]'''

===Analog Inputs 1-7===

====Specifications====
* RaceCapture/Pro has 8 analog inputs; the 8th input is wired internally to measuring battery voltage.
* Analog input range is 0 - 5v
* Input Impedance: 15K ohm

====Active Sensors/Signals====
The Analog Input Channels accept a 0-5v input signal (protected up to 40V). Connect the input from a sensor to the appropriate connection of the terminal block.
<center>[[Image:active_sensor_connection.png]]</center>

====Resistive sensor====
When connecting resistive style sensors, like many temperature and pressure sensors, one terminal of the sensor is connected to ground, and the other is connected to the Analog input, with a pullup resistor connected to the +5V Voltage Reference on the terminal block. A 2.2K resistor is recommended for most applications.
<center>[[Image:temp_sensor_connection.png]]</center>

===5V Voltage Reference===
This output provides a 5V reference to be used with the Analog Inputs. Up to 50mA is provided to supply power to active sensors, pull-up resistors and other purposes. This reference output is protected against short-circuits with an auto-resetting fuse. If the fuse is active, a low or zero voltage reading may be observed on this port. To verify an over-current situation, test the voltage on the port without any load connected.

===Analog/Frequency Outputs 1 - 4===
Depending on configuration, these outputs provide a settable 0-5v analog output voltage, or frequency output where the pulse-width and frequency can be set. These outputs can supply 50mA each.

===General Input/Output Channels 1 - 3===
Depending on configuration, these channels can accept either a digital input, or provide an output to control external devices.
* When configured for '''input''', the channel accepts a 0-5v input (protected up to 45V). Each input channel has a built-in 10K pullup resistor connected to 5V.
* When configured for '''output''', the channel provides an open-drain output that can drive 1A and is thermal / over-current protected with inductive load clamping. When the output is deactivated, a 1K ohm pull-up to +5v is present.

===Frequency/Pulse Input 1 - 3===
These input channels can be used to time the duration between digital pulses for purposes of measuring RPM, shaft speed, and so on. The input accepts 0-5V (protected up to 40V). Each input has a built-in 10K pullup resistor connected to 5V.

====TACH SIGNAL NOTES====

'''Do not connect the old-style tachometer signal directly to RaceCapture/Pro.''' This signal is typically sourced from a wire that connects directly to the (-) post of the ignition coil. These signals are 400-500v peak and can damage your RaceCapture/Pro hardware.

'''[[CoilX CoilX Sensor Module]]'''

[[Image:coilx_wiring_sm.jpg|300px]]

You can use the CoilX sensor module to safely interface this high voltage RPM signal. See the [[CoilX|CoilX page]] for more information.

Newer style tach signals sourced from the ECU will likely provide a clean square wave signal and can be connected directly to this input.

If unsure, observe the signal with an oscilloscope and/or consult technical documentation of your vehicle.

===LED Indicators===

[[File:Leds.jpg]]

* Power LED
Indicates the unit is powered up (via 12v supply or USB)
* LED1
Indicates GPS Activity. Slow flash (1Hz) indicates GPS is actively acquiring. Fast flash (10 times per second) indicates GPS is locked on to satellites.
* LED2
Indicates SD card Logging Activity. The flash rate matches the channel with the highest configured logging rate.
* LED3
Indicates error status when writing to SD Card (future error conditions will be indicated by this LED)

===Pushbutton===

[[File:Pushbutton.jpg]]

Press to manually start / stop a logging session. Note this may be overridden by any on-board scripts that may automatically start or stop logging.

===Communication Ports===

[[File:Expansionports.jpg]]

The communication ports a standard RS232 serial connection with power (up to 5v at 1.5A)
* Port 1
Used for BT module
* Port 2
Serial I/O

=Installation=
This section will give you the basic overview of installation best practices.

==Location==
Picking a location that is easily accessible is key. You will want to mount your RaceCapture so that access to the front of the unit (the side with the lights) is easy. Remember that in a driver's suit your vision and range of motion can be limited, so try to place the unit where the front is visible. For optimal perfomance of your RaceCapture unit, you should place the unit as close to the center of the vehicle's axis's as is possible. This ensures that the lateral accelerations will be minimal in the event of body roll, pitch and rotation.

==Orientation==
The unit must be mounted squarely with the vehcile. You may rotate it in 90 degree increments in along any of the three axis as you see fit, but the final result must be square against the sides, front and bottom of the vehicle. Rotating anything less than 90 degress along any one axis will lead to inaccurate G-force mesaurements. If you rotate the unit away from its default orientation (described below), you will need to remap the accelerometer when you configure the unit.

===Default Orientation===
The default configuration is setup so that the front of the unit (the side with the LEDs) is facing towards the rear of the vehicle and the side with the green connector is facing towards the front of the vehicle. The side of the unit with the RaceCapture/Pro sticker is facing up. Below is an image of the default orientation cofiguration:
[[File:RCP_MK2_3quarter_LED_Axis.png|none|200px]]
If your unit installation does not align with this orientation, you will need to re-map the channels in the firmware.

==Isolation==
Vibration from the vehicle can cause noise in the accelerometers, which can lead to dirty data. Ideally it is best to have some form of isolation between the frame of the vehicle and the RaceCapture unit. Rubber spacers work well as do adhesive strips like the 3M DualLock adhesive strips. These also allow for easy removal of the unit.

RaceCapture CustomTrackBestPractices

2016-01-13T00:36:48Z

Stieg:

=Walking/Building a Course - Best Practices=
Whether you are doing an autocross, rally, karting or whatever else you may race, sometimes you need to create your own course. Fortunately Autosport Labs has you covered for this very scenario with our custom course design tool. Using a GPS enabled tablet or phone with the RaceCapture App, you can define start & finish points as well as sector points along your track.

This page goes over the best practices in creating a course as well as in covers course setup to ensure that you get the best performance from your RaceCapture device.

==Basic System Overview==
In order to understand these recommendations, its best to first understand how RaceCapture works internally. Below is a brief definition of concepts used internally.

===Geo-Circles===
A Geo-Circle is simply a gps point and a distance. We use this information to draw a circle on the map. This is how we implement start, finish and sector points in RaceCapture firmware. When you enter the circle, you have reached that particular point. By default, the radius of a Geo-Circle is 11 meters (~36 ft). Here is what it looks like conceptually:

[[File:Race_Track_StartFinish_GeoPoint.png|200px|center]]

===Geo-Triggers===
Geo-Triggers are like Geo-Circles in that they have a gps point and a distance, but they also have one more element: a boolean indicating when the object has been triggered. We use Geo-Triggers on top of Geo-Circles in RaceCapture to prevent false positives results. Here is what it looks like conceptually:

[[File:Race_Track_StartFinish_GeoPoint_with_GeoTrigger.png|200px|center]]

===Sector Counting===
Sectors work like sequential counters. So when you start a lap with sectors on the track, RaceCapture will look for the first sector. When you reach it, it will search for the next. This process repeats until there are no more sectors, at which point it uses the finish point as the last sector point.

==Best Practices==
Now that you are armed with a basic understanding of how the internals work, these best practices are hopefully very reasonable.

===Avoid Overlapping Geo Circles With Other Parts of the Track===
Because Geo-Circles are triggered when a vehicle enters them, we must be careful in where we place them. Overlapping Geo-Circles can cause unpredictable results such as early finishes, early sector time values. This often occurs because drivers can take different drive lines. Some lines may trigger the event while others miss the Geo-Circle, and thus don't trigger the event. If there is a chance that a Geo circle overlaps an earlier part of the track, adjust its position away from the overlapping portion to prevent a false trigger. Here is what an overlapping Geo-Circle might look like:

[[File:Geo_Circle_Overlapping.png|200px|center]]

===In Stage Mode, Drive 25 M From Start Before Next Run===
Start/Finish points in RaceCapture are protected by a Geo-Trigger. Geo-Triggers are present to prevent false triggering of Geo-Circles when start and finish locations are close together. The Geo-Trigger radius is configured to be 2x the Geo-Circle radius. This means the default trigger radius is 22 meters (~72 ft) since the default Geo-Circle radius is 11 meters. In order to trigger a Geo-Trigger, you must leave the boundary it covers. Thus, if you on a Stage course (like for autocross), then after you finish you must ensure you drive than 72 feet away from the start point before you make your next run. Otherwise, RaceCapture may not trigger the start event.

===Use RaceCapture's Launch Control Feature===
Since the release of 2.8.0 firmware, RaceCapture has supported Launch Control, a feature that allows you to start from a dead stop in the start Geo-Circle and have RaceCapture properly record the start timing. This feature is available for the first lap on Circuit tracks and for every lap on Stage tracks. On Stage tracks, see the previous note about driving 25 M from the start point before your next run after finishing your previous run.

RaceCapture CustomTrackBestPractices

2016-01-13T00:33:54Z

Stieg: /* Avoid Overlapping Geo Circles With Other Parts of the Track */

=Walking/Building a Course - Best Practices=
Whether you are doing an autocross, rally, karting or whatever else you may race, sometimes you need to create your own course. Fortunately Autosport Labs has you covered for this very scenario with our custom course design tool. Using a GPS enabled tablet or phone with the RaceCapture App, you can define start & finish points as well as sector points along your track.

This page goes over the best practices in creating a course as well as in covers course setup to ensure that you get the best performance from your RaceCapture device.

==Basic System Overview==
In order to understand these recommendations, its best to first understand how RaceCapture works internally. Below is a brief definition of concepts used internally.

===Geo-Circles===
A Geo-Circle is simply a gps point and a distance. We use this information to draw a circle on the map. This is how we implement start, finish and sector points in RaceCapture firmware. When you enter the circle, you have reached that particular point. By default, the radius of a Geo-Circle is 11 meters (~36 ft).

===Geo-Triggers===
Geo-Triggers are like Geo-Circles in that they have a gps point and a distance, but they also have one more element: a boolean indicating when the object has been triggered. We use Geo-Triggers on top of Geo-Circles in RaceCapture to prevent false positives results.

===Sector Counting===
Sectors work like sequential counters. So when you start a lap with sectors on the track, RaceCapture will look for the first sector. When you reach it, it will search for the next. This process repeats until there are no more sectors, at which point it uses the finish point as the last sector point.

==Best Practices==
Now that you are armed with a basic understanding of how the internals work, these best practices are hopefully very reasonable.

===Avoid Overlapping Geo Circles With Other Parts of the Track===
Because Geo-Circles are triggered when a vehicle enters them, we must be careful in where we place them. Overlapping Geo-Circles can cause unpredictable results such as early finishes, early sector time values. This often occurs because drivers can take different drive lines. Some lines may trigger the event while others miss the Geo-Circle, and thus don't trigger the event. If there is a chance that a Geo circle overlaps an earlier part of the track, adjust its position away from the overlapping portion to prevent a false trigger. Here is what an overlapping Geo-Circle might look like:

[[File:Geo_Circle_Overlapping.png|200px]]

===In Stage Mode, Drive 25 M From Start Before Next Run===
Start/Finish points in RaceCapture are protected by a Geo-Trigger. Geo-Triggers are present to prevent false triggering of Geo-Circles when start and finish locations are close together. The Geo-Trigger radius is configured to be 2x the Geo-Circle radius. This means the default trigger radius is 22 meters (~72 ft) since the default Geo-Circle radius is 11 meters. In order to trigger a Geo-Trigger, you must leave the boundary it covers. Thus, if you on a Stage course (like for autocross), then after you finish you must ensure you drive than 72 feet away from the start point before you make your next run. Otherwise, RaceCapture may not trigger the start event.

===Use RaceCapture's Launch Control Feature===
Since the release of 2.8.0 firmware, RaceCapture has supported Launch Control, a feature that allows you to start from a dead stop in the start Geo-Circle and have RaceCapture properly record the start timing. This feature is available for the first lap on Circuit tracks and for every lap on Stage tracks. On Stage tracks, see the previous note about driving 25 M from the start point before your next run after finishing your previous run.

File:Race Track StartFinish GeoPoint with GeoTrigger.png

2016-01-13T00:33:46Z

Stieg: Shows what a Geo-Point protected by a Geo-Trigger looks like.

Shows what a Geo-Point protected by a Geo-Trigger looks like.

File:Race Track StartFinish GeoPoint.png

2016-01-13T00:32:56Z

Stieg: Shows what a Geo-Point looks like at the start/finish line.

Shows what a Geo-Point looks like at the start/finish line.

File:Geo Circle Overlapping.png

2016-01-13T00:28:10Z

Stieg: Shows a Geo-Circle overlapping onto another part of the track

Shows a Geo-Circle overlapping onto another part of the track

RaceCapture CustomTrackBestPractices

2016-01-13T00:07:19Z

Stieg:

=Walking/Building a Course - Best Practices=
Whether you are doing an autocross, rally, karting or whatever else you may race, sometimes you need to create your own course. Fortunately Autosport Labs has you covered for this very scenario with our custom course design tool. Using a GPS enabled tablet or phone with the RaceCapture App, you can define start & finish points as well as sector points along your track.

This page goes over the best practices in creating a course as well as in covers course setup to ensure that you get the best performance from your RaceCapture device.

==Basic System Overview==
In order to understand these recommendations, its best to first understand how RaceCapture works internally. Below is a brief definition of concepts used internally.

===Geo-Circles===
A Geo-Circle is simply a gps point and a distance. We use this information to draw a circle on the map. This is how we implement start, finish and sector points in RaceCapture firmware. When you enter the circle, you have reached that particular point. By default, the radius of a Geo-Circle is 11 meters (~36 ft).

===Geo-Triggers===
Geo-Triggers are like Geo-Circles in that they have a gps point and a distance, but they also have one more element: a boolean indicating when the object has been triggered. We use Geo-Triggers on top of Geo-Circles in RaceCapture to prevent false positives results.

===Sector Counting===
Sectors work like sequential counters. So when you start a lap with sectors on the track, RaceCapture will look for the first sector. When you reach it, it will search for the next. This process repeats until there are no more sectors, at which point it uses the finish point as the last sector point.

==Best Practices==
Now that you are armed with a basic understanding of how the internals work, these best practices are hopefully very reasonable.

===Avoid Overlapping Geo Circles With Other Parts of the Track===
Because Geo-Circles are triggered when a vehicle enters them, we must be careful in where we place them. Overlapping Geo-Circles can cause unpredictable results such as early finishes, early sector time values. This often occurs because drivers can take different drive lines. Some lines may trigger the event while others miss the Geo-Circle, and thus don't trigger the event. If there is a chance that a Geo circle overlaps an earlier part of the track, adjust its position away from the overlapping portion to prevent a false trigger.

===In Stage Mode, Drive 25 M From Start Before Next Run===
Start/Finish points in RaceCapture are protected by a Geo-Trigger. Geo-Triggers are present to prevent false triggering of Geo-Circles when start and finish locations are close together. The Geo-Trigger radius is configured to be 2x the Geo-Circle radius. This means the default trigger radius is 22 meters (~72 ft) since the default Geo-Circle radius is 11 meters. In order to trigger a Geo-Trigger, you must leave the boundary it covers. Thus, if you on a Stage course (like for autocross), then after you finish you must ensure you drive than 72 feet away from the start point before you make your next run. Otherwise, RaceCapture may not trigger the start event.

===Use RaceCapture's Launch Control Feature===
Since the release of 2.8.0 firmware, RaceCapture has supported Launch Control, a feature that allows you to start from a dead stop in the start Geo-Circle and have RaceCapture properly record the start timing. This feature is available for the first lap on Circuit tracks and for every lap on Stage tracks. On Stage tracks, see the previous note about driving 25 M from the start point before your next run after finishing your previous run.

RaceCapture CustomTrackBestPractices

2016-01-13T00:06:27Z

Stieg:

=Walking/Building a Course - Best Practices=
Whether you are doing an autocross, rally, karting or whatever else you may race, sometimes you need to create your own course. Fortunately Autosport Labs has you covered for this very scenario with our custom course design tool. Using a GPS enabled tablet or phone with the RaceCapture App, you can define start & finish points as well as sector points along your track.

This page goes over the best practices in creating a course as well as in covers course setup to ensure that you get the best performance from your RaceCapture device.

==Basic System Overview==
In order to understand these recommendations, its best to first understand how RaceCapture works internally. Below is a brief definition of concepts used internally.

===Geo-Circles===
A Geo-Circle is simply a gps point and a distance. We use this information to draw a circle on the map. This is how we implement start, finish and sector points in RaceCapture firmware. When you enter the circle, you have reached that particular point. By default, the radius of a Geo-Circle is 11 meters (~36 ft).

===Geo-Triggers===
Geo-Triggers are like Geo-Circles in that they have a gps point and a distance, but they also have one more element: a boolean indicating when the object has been triggered. We use Geo-Triggers on top of Geo-Circles in RaceCapture to prevent false positives results.

===Sector Counting===
Sectors work like sequential counters. So when you start a lap with sectors on the track, RaceCapture will look for the first sector. When you reach it, it will search for the next. This process repeats until there are no more sectors, at which point it uses the finish point as the last sector point.

=Best Practices=
Now that you are armed with a basic understanding of how the internals work, these best practices are hopefully very reasonable.

==Avoid Overlapping Geo Circles With Other Parts of the Track==
Because Geo-Circles are triggered when a vehicle enters them, we must be careful in where we place them. Overlapping Geo-Circles can cause unpredictable results such as early finishes, early sector time values. This often occurs because drivers can take different drive lines. Some lines may trigger the event while others miss the Geo-Circle, and thus don't trigger the event. If there is a chance that a Geo circle overlaps an earlier part of the track, adjust its position away from the overlapping portion to prevent a false trigger.

==In Stage Mode, Drive 25 M From Start Before Next Run==
Start/Finish points in RaceCapture are protected by a Geo-Trigger. Geo-Triggers are present to prevent false triggering of Geo-Circles when start and finish locations are close together. The Geo-Trigger radius is configured to be 2x the Geo-Circle radius. This means the default trigger radius is 22 meters (~72 ft) since the default Geo-Circle radius is 11 meters. In order to trigger a Geo-Trigger, you must leave the boundary it covers. Thus, if you on a Stage course (like for autocross), then after you finish you must ensure you drive than 72 feet away from the start point before you make your next run. Otherwise, RaceCapture may not trigger the start event.

==Use RaceCapture's Launch Control Feature==
Since the release of 2.8.0 firmware, RaceCapture has supported Launch Control, a feature that allows you to start from a dead stop in the start Geo-Circle and have RaceCapture properly record the start timing. This feature is available for the first lap on Circuit tracks and for every lap on Stage tracks. On Stage tracks, see the previous note about driving 25 M from the start point before your next run after finishing your previous run.

RaceCapture CustomTrackBestPractices

2016-01-13T00:02:13Z

Stieg: /* In Stage Mode, Drive 25 M from Start Before Next Run */

=Walking/Building a Course - Best Practices=
Whether you are doing an autocross, rally, karting or whatever else you may race, sometimes you need to create your own course. Fortunately Autosportlabs has you covered for this very scenario with our custom course design tool. Using a GPS enabled tablet or phone with the RaceCapture App, you can define start & finish points as well as sector points along your track.

This page goes over the best practices in creating a course as well as in covers course setup to ensure that you get the best performance from your RaceCapture device.

==Basic System Overview==
In order to understand these recommendations, its best to first understand how RaceCapture works internally. Below is a brief definition of concepts used internally.

===Geo Circles===
A geo circle is simply a gps point and a distance. We use this information to draw a circle on the map. This is how we implement start, finish and sector points in RaceCapture firmware. When you enter the circle, you have reached that particular point. By default, the radius of a geo circle is 11 meters (~36 ft).

===Geo Triggers===
Geo triggers are like geo circles in that they have a gps point and a distance, but they also have one more element: a triggered boolean. We use geo triggers on top of geo circles in RaceCapture to prevent false positives results.

===Sector Counting===
Sectors work like sequential counters. So when you start a lap with sectors on the track, RaceCapture will look for the first sector. When you reach it, it will search for the next. This process repeats until there are no more sectors, at which point it uses the finish point as the last sector point.

=Best Practices=
Now that you are armed with a basic understanding of how the internals work, these best practices are hopefully very reasonable.

==Avoid Overlapping Geo Circles With Other Parts of the Track==
Because geo circles are triggered when a vehicle enters them, we must be careful in where we place them. Overlapping GeoCircles can cause unpredictable results such as early finishes, early sector time values. This often occurs because drivers can take different drive lines. Some lines may trigger the event while others miss the geo circle, and thus don't trigger the event. If there is a chance that a Geo circle overlaps an earlier part of the track, adjust its position away from the overlapping portion to prevent a false trigger.

==In Stage Mode, Drive 25 M From Start Before Next Run==
Start/Finish points in RaceCapture are protected by a GeoTrigger. Geo triggers are present to prevent false triggering of GeoCircles when start and finish locations are close together. The GeoTrigger radius is configured to be 2x the geo circle radius. This means the default trigger radius is 22 meters (~72 ft) since the default geo circle radius is 11 meters. In order to trigger a GeoTrigger, you must leave the boundary it covers. Thus, if you on a Stage course (like for autocross), then after you finish you must ensure you drive than 72 feet awar from the start point before you make your next run. Otherwise, RaceCapture may not trigger the start event.

==Use RaceCapture's Launch Control Feature==
Since the release of 2.8.0 firmware, RaceCapture has supported Launch Control, a feature that allows you to start from a dead stop in the start geo circle and have RaceCapture properly record the start timing. This feature is available for the first lap on Circuit tracks and for every lap on Stage tracks. On Stage tracks, see the previous note about driving 25 M from the start point before your next run after finishing your previous run.

RaceCapture CustomTrackBestPractices

2016-01-13T00:01:54Z

Stieg: Created page with "=Walking/Building a Course - Best Practices= Whether you are doing an autocross, rally, karting or whatever else you may race, sometimes you need to create your own course. F..."

=Walking/Building a Course - Best Practices=
Whether you are doing an autocross, rally, karting or whatever else you may race, sometimes you need to create your own course. Fortunately Autosportlabs has you covered for this very scenario with our custom course design tool. Using a GPS enabled tablet or phone with the RaceCapture App, you can define start & finish points as well as sector points along your track.

This page goes over the best practices in creating a course as well as in covers course setup to ensure that you get the best performance from your RaceCapture device.

==Basic System Overview==
In order to understand these recommendations, its best to first understand how RaceCapture works internally. Below is a brief definition of concepts used internally.

===Geo Circles===
A geo circle is simply a gps point and a distance. We use this information to draw a circle on the map. This is how we implement start, finish and sector points in RaceCapture firmware. When you enter the circle, you have reached that particular point. By default, the radius of a geo circle is 11 meters (~36 ft).

===Geo Triggers===
Geo triggers are like geo circles in that they have a gps point and a distance, but they also have one more element: a triggered boolean. We use geo triggers on top of geo circles in RaceCapture to prevent false positives results.

===Sector Counting===
Sectors work like sequential counters. So when you start a lap with sectors on the track, RaceCapture will look for the first sector. When you reach it, it will search for the next. This process repeats until there are no more sectors, at which point it uses the finish point as the last sector point.

=Best Practices=
Now that you are armed with a basic understanding of how the internals work, these best practices are hopefully very reasonable.

==Avoid Overlapping Geo Circles With Other Parts of the Track==
Because geo circles are triggered when a vehicle enters them, we must be careful in where we place them. Overlapping GeoCircles can cause unpredictable results such as early finishes, early sector time values. This often occurs because drivers can take different drive lines. Some lines may trigger the event while others miss the geo circle, and thus don't trigger the event. If there is a chance that a Geo circle overlaps an earlier part of the track, adjust its position away from the overlapping portion to prevent a false trigger.

==In Stage Mode, Drive 25 M from Start Before Next Run==
Start/Finish points in RaceCapture are protected by a GeoTrigger. Geo triggers are present to prevent false triggering of GeoCircles when start and finish locations are close together. The GeoTrigger radius is configured to be 2x the geo circle radius. This means the default trigger radius is 22 meters (~72 ft) since the default geo circle radius is 11 meters. In order to trigger a GeoTrigger, you must leave the boundary it covers. Thus, if you on a Stage course (like for autocross), then after you finish you must ensure you drive than 72 feet awar from the start point before you make your next run. Otherwise, RaceCapture may not trigger the start event.

==Use RaceCapture's Launch Control Feature==
Since the release of 2.8.0 firmware, RaceCapture has supported Launch Control, a feature that allows you to start from a dead stop in the start geo circle and have RaceCapture properly record the start timing. This feature is available for the first lap on Circuit tracks and for every lap on Stage tracks. On Stage tracks, see the previous note about driving 25 M from the start point before your next run after finishing your previous run.

RaceTracks

2015-08-17T17:47:43Z

Stieg: Clean up this page, add info on how to do sector selection

__NOTOC__

=How to create / submit a track map=

==Pick a Track==
Pick a track map below that isn't completed.

==Open Up a Basic Text Editor==
You will need a basic text editor to copy and past information into. Applications like Notepad, Textedit, Gedit all work very well.

== Open Up The Drawing Tool ==
Use this handy [http://www.birdtheme.org/useful/v3tool.html Map Drawing tool] to create an outline of the race track as well as find GeoPoints. I will assume you are using it throughout the rest of this tutorial.

== Record Basic Track Info==
We need a few basic things to get going. They are as follows:
*Track Name
*Track Configuration (if known)
*Country Track is Located In
*Start/Finish GeoPoint on track.
*Center area of track (We use this for zooming and display purposes).

Add all that information into your text editor.

==Draw the Track==
Now its time to draw the outline of the track. Clear the tool above using the "Clear Map" button and do the following:

# Find the race track track using the search bar and zoom in on the track.
# Locate the start / finish line and make that your first point by clicking it.
# Follow the contour of the track by clicking around the track, making sure your lines are '''in the centerline of the track''' (This is really important).
# If you make a mistake, you can undo points by clicking the "Delete Last Point" button.

When you are finished, copy the text blob from the tool into the text editor. Label the blob as "Outline"

''Tips:''
* Zoom all the way in on the map to get the best placement accuracy
* Make more points in curves so it looks smooth.
* Draw the lines using the centerline of the track.

==Record Sector Points ''(Optional)''==
If you want to go the extra mile and be extra awesome, you can include sector points. These are points that allow us to partition
the track into sections so we can get timing info for individual sections of the track. However there is a catch, we can only support up to 20 sector points per track (not including start/finish). To add sector data, do the following:

#Use the same tool. Before you start, clear out any data by selecting the "Clear Map" button.
#Think about how you would logically divide the track in your mind. What corners or sections are most important to you?
#With that in mind, select these points. Don't worry about the shape you draw, we are interested in the points.
#* REMEMBER: You can only have up to 20 points. DO NOT include start finish as one of these points.

When you are finished, copy the text blob from the tool into the text editor. Label the blob as "Sectors"

==Submit It!==
When you've gotten all the data described above, copy and paste all of the text from your text editor into an email and [mailto:racecapture@autosportlabs.com submit it to us]. Be sure you included the basic track data! We will review the track data and if sufficient, incorporate it into our Mobile app and online!

'''Thank you from the Autosport Labs team!'''

=Tracks=
To see a list of track maps we have in our database, visit this page: http://race-capture.com/venues

RaceCapturePro Lua Scripting

2015-08-02T19:38:28Z

Stieg: Add the Time Info section at the bottom for the new LUA methods

==Example Scripts and How-Tos==

'''[[RaceCapturePro Lua Scripting Examples|Lua Scripting Examples]]'''

==General Input / Output (GPIO) Functions==

===getGpio( channel )===
Retrieves the state of the specified GPIO channel

*params
** channel: integer 0 - 2
*returns:
** state: 1 = channel is high, 0 = channel is low

When the channel is configured for input mode, a voltage high input (> 2 volts) will read as 1; a voltage low will read as 0. A disconnected channel will read as high due to the internal pullup resistor.

When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground) and 0 when the channel is deactivated (pullup resistor is active)

===setGpio ( channel, state )===
Sets the state of the GPIO channel when the channel is configured for output mode.

*params
** channel: integer 0 - 2, state - 1 = output active; 0 = output inactive
*returns:
** none

When the state specified is 1, the output is active (transistor is connected to ground). When state is 0, transistor is disconnected, and pullup resistor is active.

When configured for input mode this function has no effect.

===getButton()===
Gets the state of the front panel pushbutton.

*params
** none
*returns
** state: 1 = pushbutton is depressed; 0 = pushbutton is not depressed

==PWM / Analog Output functions==

===setPwmDutyCycle( channel, dutyCyclePct )===
Sets the duty cycle of the specified PWM / Analog output channel to the specified duty cycle percentage

*params
** channel: PWM / Analog output channel 0 - 3
*returns
** none

===setPwmClockFreq( frequency )===
Sets the clock frequency of the PWM outputs

*params
** frequency: the frequency of the PWM clock, in Hz. Supported range is 320-40000 Hz
* returns
** none

===setAnalogOut( channel, voltage )===
Sets the output voltage of the specified PWM / Analog output channel to the specified period. A convenience function equivalent to setPwmDutyCycle that translates voltage to PWM percentage.

*params
** channel: PWM / Analog output channel 0 - 3
** voltage: the specified output voltage ( 0 - 5v)
** returns
* none

==Timer / RPM Sensor Functions==

===getTimerRpm(channel)===
Returns the current RPM of the specified timer input channel. Note, the timer channel configuration must be set to RPM mode.

*params
** channel: Timer channel 0 - 2
** returns: RPM value

===getTimerPeriodMs(channel)===
Returns the current duration of the full cycle pulse of the specified timer input channel, in milliseconds. Note the timer channel configuration must be set to Duration mode.

*params
** channel: Timer channel 0 - 3
** returns: millisecond value

===getTimerFreq(channel)===
Returns the current frequency present on the specified timer input channel, in Hz. Note the timer channel configuration must be set to Frequency Mode.

*params
** channel: Timer channel 0 - 3
** returns: Frequency in Hz

===getTimerRaw(channel)===
Returns the current raw timer value as measured on the specified timer input channel.

*params
** channel: Timer channel 0 - 3
** returns: Raw timer value between 0 - 65535



==Analog Sensor Functions==

===getAnalog(channel)===
Reads the scaled analog value for the specified analog input channel.
*params
** channel: Analog input channel 0 - 7
*** Note: channel 7 is internally dedicated to battery voltage.
** returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

==Accelerometer / Yaw Sensor Functions==

===getImu(channel)===
Reads the specified IMU channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The value scaled to G force, or degrees/sec depending on the channel selected

===getImuRaw(channel)===
Reads the raw value of the specified accelerometer or yaw channel
* params
** channel (0 - 2 for accelerometer, 3 for yaw gyro sensor)
* returns
** The raw accelerometer value

==GPS Sensor Functions==

===getGpsPos()===
Reads the current position as measured by the attached GPS module ''coming in firmware 2.0''
* params
** none
* returns
** Latitude: latitude in decimal degrees
** Longitude: longitude in decimal degress

===getGpsSpeed()===
Provides the current speed as measured by the attached GPS module
* params
** (none)
* returns
** The current speed in MPH

===getGpsQuality()===
Provides the current GPS quality indicator as indicated by the attached GPS module
* params
** (none)
* returns
** The current GPS quality indicator
** 0: No fix; 1: Fixed; 2: SPS Fix; 3: Differential Fix

===getGpsTime()===
Provides the current GPS time as indicated by the attached GPS module (in NMEA format) ''todo: document this''
* params
** (none)
* returns
** The current GPS time value

===getGpsDist()===
Provides the current GPS calculated distance from the beginning of the logging session, or from the start finish line, if configured.
* params
** (none)
* returns
** The distance, in Miles

===getLapCount()===
Provides the current Lap Count as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The number of laps detected since the logging session started

===getLapTime()===
Provides the last lap time as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** The last measured lap time in decimal minutes / seconds

===getGpsSec()===
Provides the number of seconds since midnight, as measured by the GPS module. ''todo: how does this relate to timezone? GMT or local?''
* params
** (none)
* returns
** number of seconds since midnight, as measured by the attached GPS module

===getAtStartFinish()===
Indicates if within the start finish line target as determined by the start/finish line configuration and measured by the attached GPS module.
* params
** (none)
* returns
** 1 if currently within the start/finish line target, 0 if outside

===getTimeDiff(time1, time2)===
Utility function to calculate the absolute difference between two time values, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time1
** time2
* returns
** The absolute difference between the specified values

===getTimeSince(time)===
Utility function to calculate the time since midnight, in seconds. ''todo: investigate the need for this function. may be eliminated in 1.2 firmware''
* params
** time
* returns
** The number of seconds since midnight

==CAN Bus functions==

===initCAN(channel, baud )===
''available in firmware 2.0''
Initializes the CAN bus module. Normally this is done when RaceCapture/Pro powers on; use this function if you need to change the CAN baud rate on the fly.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
* returns
** 1 if successful, 0 if initialization fails, nil if parameters are incorrect

===txCAN(channel, id, isExtended, data, [timeout] )===
''available in firmware 2.0''
Transmit a CAN message.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** data: CAN message payload; array up to 8 elements long.
** timeout: (optional) specify a timeout for sending this message. if the transmit queue is full, will block for the specified milliseconds. Defaults to 100ms
* returns
** 1 if successful, 0 if failed, nil if parameters are incorrect

Example:
channel = 0
id = 1234
ext = 0
data = {11,22,33}
res = txCAN(channel, id, ext, data)

===rxCAN(channel, [timeout] )===
''available in firmware 2.0''
Receive a CAN message, if available.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** timeout (optional). read timeout in milliseconds. defaults to 100ms
* returns
** identifier: The Identifier value of the message, either in standard (11 bit) or extended (29 bit) format.
** isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** Data: CAN message payload; array up to 8 elements long.

If no CAN message was received, the function returns nil

Example:
id, ext, data = rxCAN(0, 100) --100ms timeout
if id ~= nil then
println("CAN rx: " ..id .." " ..data[1]) --print ID and first element of received message
end

===setCANfilter(channel, filterId, extended, filter, mask )===
''available in firmware 2.0''
Sets the specified CAN filter ID, to ignore messages with a particular address. Must use in combination with setCANMask() to set a complete filter and mask.
* params
** channel: The CAN channel. 0 for the first channel, 1 for the 2nd, if supported on the hardware
** filterId: The id of the filter. Up to 6 filters are supported on MK1, 15 per channel on MK2. Filter ids start at 0.
** extended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
** filter: Pattern value for CAN filter
** mask: the mask for the CAN filter
* returns
** 1 for success, 0 for fail, nil if parameters are incorrect

===readOBD2( PID )===
''available in firmware 2.0''
Reads an OBD2 PID and returns the calculated value. This is a convenience method wrapped around the built-in CAN functions.
* params
** The OBD2 PID to read. Supported PIDs (TBD documented)
* returns
** The calculated PID value, or nil if the OBD2 PID was invalid or could not be read (e.g. CAN receive message timeout)

==Logger Control Functions==

===onTick()===
* params:
** (none)
* returns:
** (none)

The onTick() function is the main loop where scripting activity takes place. By default it is called by RaceCapture/Pro every 1 second (1Hz). The rate can be adjusted using the setTickRate() function.

Example:

function onTick()
println("Hello") --write something to the log
end

===setTickRate(rate)===
Sets the rate at which the onTick() function is called
* params
** rate: The rate the onTick() function is called, in Hz. Max tick rate is 30Hz.
* returns
** (none)

===startLogging()===
Begins a logging session
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current logging session. If not logging, this function has no effect.
* params
** (none)
* returns
** (none)

===setLed( led, state )===
Sets the state of a front panel LED
* params
** led (1-3)
** state : 1 = on, 0 = off
* returns
** (none)

==Serial Port Communications==

These function calls allow reading / writing line oriented data from the built in serial ports.

===Port mappings===
0 = USB port 
1 = GPS port 
2 = Internal telemetry port (MK2 only) 
3 = Wireless / Bluetooth port 
4 = Auxiliary port 

* '''Note''': We only recommend using ports 3 and 4 for connecting script to external devices. Ports 0 - 2 have been included for reference; using them may interfere with normal operations of the unit.

===initSer( port, baud, bits, parity, stopBits)===
Initializes the specified serial port

* params
** port: The port to initialize. (defaults to Auxiliary port)
** baud: The baud rate to set (defaults to 115200)
** bits: Number of bit in the message (8 or 7) (defaults to 8)
** parity: (1 = Even Parity, 2 = Odd Parity, 0 = No Parity) (defaults to No Parity)
** stopBits: number of stop bits (1 or 2) (defaults to 1)

* returns
** 1 if initialization succeeds, -1 if parameters are incorrect

===readCSer( port )===
Read a character from the specified serial port

* params
** port: The port to read. (required)
** timeout - the read timeout, in ms.

* returns
** the character read, or nil if the timeout was reached

===readSer( port )===
Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port, or a timeout occurs.
* params
** port: Serial port 0 - 4
** timeout - the read timeout, in ms.
** returns: a line of serial data, or nil if the timeout was reached

===writeCSer( port, data )===
Writes the specified character to the serial port. The call will block until the character is written.
* params:
** port - the serial port to write
** char - the character to write.

* returns:
(no return values)

===writeSer( port, data )===
Writes a line of data to the specified serial port, appending a newline at the end. The call will block until all characters are written.
* params
** port: Serial port 0 - 4
** data: the data in string format

* returns:
(no return values)

==Logger Configuration Functions==

===flashLoggerCfg()===
Writes the current configuration in RAM to flash memory.
* params
** (none)
* returns
** (none)

===setPwmClockFreq( freq )===
Sets the clock frequency for all PWM channels
* params
** freq: The clock frequency ''todo: what units?''
* returns
** (none)

===getPwmClockFreq()===
Gets the PWM clock frequency controlling all PWM channels
* params
** (none)
* returns
** the PWM clock frequency ''todo: what units?''

===calibrateImuZero()===
Automatically Calibrates the accelerometer zero position.
* params
** (none)
* returns
** (none)

==Virtual Channels==

===addChannel( name, sampleRate, [precision], [min], [max], [units] )===
''available in firmware 2.0''
Adds a virtual channel. This virtual channel remains in memory during runtime; it is not persisted in the configuration. Up to 30 virtual channels can be created.
* params
** name: The name of the channel, up to 10 characters long. We recommend using an existing System channel name as defined by the app when possible.
** sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
** precision: (optional) the numerical precision (number of decimal places) used when logging to SD and telemetry. Defaults to 2
** min: (optional) The min expected value for this channel. Defaults to 0
** max: (optional) The max expected value for this channel. Defaults to 1000
** units: (optional) The units label for this channel. Defaults to empty string / none

* returns
** the id of the new virtual channel, or NIL if the virtual channel could not be created. Use this id for setting the channel value (see setChannel() )

===setChannel( channelId, value )===
''available in firmware 2.0''
Updates the value of a previously created virtual channel.
* params
** channelId: the ID of the channel provided by addChannel()
** value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1)

function onTick()
temp = getAnalog(0) --read analog channel 0
temp = temp * 1000
setChannel(id, temp) --sets the virtual channel value
end

==Time Info==
These methods get you information about dates and time. This is useful in controlling script behavior or just knowing what time it is.

===getUptime()===
''Available in Firmware 2.8.4 and Newer'' 
Returns the number of miliseconds since the device last started. This is always available and is the most consistent way to time things in LUA script on RaceCapture.

* Returns
** Number of milliseconds since CPU boot.

===getDateTime()===
''Available in Firmware 2.8.4 and Newer'' 
Returns date and time info to the best of the systems ability. Only available after GPS lock has been established. Will return epoch time (Jan 1, 1970 00:00:000) if time is not available.

* Returns: A list of date and time information in the following order:
** Year
** Month
** Day
** Hour
** Second
** Millisecond