RaceCapturePro Lua Scripting

Revision as of 17:17, 20 November 2014 by Brentp (talk | contribs) (updated addChannel and txCAN / rxCAN api)

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

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

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(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.

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


Example: 

id = 1234
ext = 0
data = {11,22,33}
res = txCAN(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

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

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 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)
    • 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
    • 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
Retrieved from "https://wiki.autosportlabs.com/index.php?title=RaceCapturePro_Lua_Scripting&oldid=5762"