RaceCapturePro Lua Scripting

From Autosport Labs

Jump to: navigation, search

Contents

Example Scripts and How-Tos

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

setPwmPeriod( channel, period )

Sets the period of the specified PWM / Analog output channel to the specified period

  • params
    • channel: PWM / Analog output channel 0 - 3
    • period: The period value
    • 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 - 3
    • 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

getTimerFrequency(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
    • returns: Scaled / calculated value for the specified analog channel as defined in the channel scaling configuration

getAnalogRaw(channel)

Reads the raw analog value for the specified analog input channel.

  • params
    • channel: Analog input channel 0 - 7
    • returns: The raw value measured by the 10 bit Analog to Digital Converted on the specified analog channel, between 0 - 1023

Accelerometer / Yaw Sensor Functions

getAccel(channel)

Reads the specified accelerometer 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

getAccelRaw(channel)

Reads the raw ADC 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

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( 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
    • baud rate: Supported baud rates: 100000, 125000, 250000, 500000, 1000000
  • returns
    • 1 if successful, 0 if initialization fails.

txCAN( id, isExtended, data )

available in firmware 2.0 Transmit a CAN message.

  • params
    • 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.

Example:

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

rxCAN( timeout )

available in firmware 2.0 Receive a CAN message, if available.

  • params
    • timeout (optional). read timeout in milliseconds
  • 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(100) --100ms timeout
if id ~= nil then
  println("CAN rx: " ..id .." " ..data[0]) --print ID and first element of received message
end

setCANfilter( filterId, filterPattern )

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
    • filter ID (0-5). Up to 6 filters are supported. Typically you will use filter ID 0-1.
    • filter Pattern value for CAN filter
    • isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
  • returns
  • 1 for success, 0 for fail

setCANMask( maskId, maskPattern )

available in firmware 2.0 Sets the specified CAN filter Mask, to ignore messages with a particular address. Must use in combination with setCANFilter() to set a complete filter and mask

  • params
    • Mask (0-1). Up to 2 masks are supported. Typically you will use mask 0.
    • filter Pattern value for CAN mask
    • isExtended: 0 for Standard (11 bit) Identifier or 1 for Extended (29 bit) Identifier.
  • returns
  • 1 for success, 0 for fail

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)

readSerial( port )

Read a line of data from the specified serial port. This command blocks until a newline ('\n') character is received on the port.

  • params
    • port: Serial port 0 - 1
    • returns: a line of serial data

writeSerial( port, data )

Writes data to the specified serial port.

  • params
    • port: Serial port 0 - 1
    • data: the data in string format

Logger Configuration Functions

flashLoggerConfig()

Writes the current configuration in RAM to flash memory.

  • params
    • (none)
  • returns
    • (none)

setAnalogSampleRate( channel, rate )

Sets the sample rate for the specified channel

  • params
    • channel
    • sampleRate
  • returns
    • (none)

getAnalogSampleRate()

Gets the sample rate for the specified channel

  • params
    • (none)
  • returns
    • (none)

setPwmClockFrequency( freq )

Sets the clock frequency for all PWM channels

  • params
    • freq: The clock frequency todo: what units?
  • returns
    • (none)

getPwmClockFrequency()

Gets the PWM clock frequency controlling all PWM channels

  • params
    • (none)
  • returns
    • the PWM clock frequency todo: what units?

setPwmSampleRate( channel, rate )

Sets the sample rate for the specified PWM channel

  • params
    • channel: the PWM channel
    • rate: the sample rate to set
  • returns
    • (none)

getPwmSampleRate( channel )

Gets the PWM sample rate for the specified PWM channel

  • params
    • channel: the PWM channel
  • returns
    • rate: the currently configured sample rate

setGpsSampleRate

Sets the sample rate for GPS logging features

  • params
    • sampleRate - sample rate in Hz. Function has no effect if the specified value does not match a supported sample rate.
  • returns
    • (none)

getGpsSampleRate

Gets the sample rate for the specified channel

  • params
    • (none)
  • returns
  • sampleRate - the configured sample rate, in Hz

setGpioSampleRate

Sets the sample rate for the specified GPIO channel

  • params
    • channel - a supported GPIO channel (0 - 2)
    • sampleRate - sample rate in Hz. Function has no effect if the specified value does not match a supported sample rate.
  • returns
    • (none)

getGpioSampleRate

Gets the sample rate for the specified GPIO channel

  • params
    • (none)
  • returns
  • sampleRate - the configured sample rate, in Hz

setGpioConfig( channel, config )

Sets the input/output configuration for the specified GPIO channel

  • params
    • channel - a supported GPIO channel (0 - 2)
    • config - 0 = input mode; 1 = output mode. Note, hardware jumpers must also be set to reflect configuration
  • returns
    • (none)

getGpioConfig

Gets the input/output configuration for the specified GPIO channel

  • params
    • channel - a supported GPIO channel (0 - 2)
  • returns
    • config - 0 = input mode; 1 = output mode.

setTimerSampleRate( sampleRate )

Sets the sample rate for the specified timer channel

  • params
    • channel - a supported timer channel (0 - 2)
    • sampleRate - sample rate in Hz. Function has no effect if the specified value does not match a supported sample rate.
  • returns
    • (none)

getTimerSampleRate()

Gets the sample rate for the specified timer channel

  • params
    • (none)
  • returns
  • sampleRate - the configured sample rate, in Hz

setAccelSampleRate( sampleRate )

Sets the sample rate for the specified accelerometer or gyro channel

  • params
    • channel - a supported channel (0,1,2 for accelerometer; 4 for yaw sensor gyro)
    • sampleRate - sample rate in Hz. Function has no effect if the specified value does not match a supported sample rate.
  • returns
    • (none)

getAccelSampleRate()

Gets the sample rate for the specified accelerometer or gyro channel

  • params
    • a supported channel (0,1,2 for accelerometer; 4 for yaw sensor gyro)
  • returns
  • sampleRate - the configured sample rate, in Hz

calibrateAccelZero()

Automatically Calibrates the accelerometer zero position.

  • params
    • (none)
  • returns
    • (none)

setGpsStartFinish( latitude, longitude, target )

Sets the start/finish line target, used for lap time calculations.

  • params
    • latitude - latitude in decimal degrees
    • longitude - longitude in decimal degrees
    • target - radius of GPS target, in degrees
  • returns
    • (none)

latitude, longitude, target = getGpsStartFinish()

Gets the start/finish line target, used for lap time calculations.

  • params
    • (none)
  • returns
    • latitude - latitude in decimal degrees
    • longitude - longitude in decimal degrees
    • target - radius of GPS target, in degrees

Virtual Channels

addChannel( name, sampleRate )

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 10 virtual channels can be created.

  • params
    • name: The name of the channel. Must be a channel name known to the system, up to 10 characters long.
    • sampleRate: A supported sample rate (1,10,25,50,100,200Hz)
  • returns
    • the Id of the new virtual channel, or nil if the virtual channel could not be created.

setChannel( channelId, value )

available in firmware 2.0 Updates the value of a previously created virtual channel.

  • params
    • Id: the ID of the channel provided by addChannel()
    • Value: the new value to set for the virtual channel

Example:

id = addChannel("EGT", 1) --channel name EGT must exist in the list of known channels

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