Autosport Labs - User contributions [en]

ESP32-CAN-X2

2024-11-05T19:51:11Z

Ddimensia: /* Board Pinout */ Fixed SV2 12-13 pin descriptions

=Introduction=

ESP32-CAN-X2 is an ESP32-based development board specifically designed for CAN communication. This board has all the features of a modern ESP32 development board, integrated Wi-Fi and Bluetooth, along with the extended CAN controller. Autosport Labs has specifically designed it for CAN communication along with fast processing and computation options.

This is a complete how-to-use guide and this user guide will describe each and every step to use the board and harness the maximum potential of the board.

=Features=

Features of ESP32-CAN-X2 development board:

* Based on ESP32-S3-WROOM-1-N8R8 microcontroller powerful dual-core Xtensa LX6 CPU running at up to 240 MHz.
* 384 KB ROM, 512 KB SRAM, 16 KB SRAM in RTC, 8 MB PSRAM
* Two LED’s : Power LED and user defined LED1
* Integrated Wi-Fi (802.11b/g/n) and Bluetooth capabilities
* Reset and Boot push button
* USB-C type socket for flashing, and power supply
* Integrated antenna for long range communication
* Additional CAN communication controller CAN using MCP2515
* 6-pin header is strategically positioned at the top for CAN communication
* Easy-to-interface programming. Required no external debugger for flashing
* Integrated CAN transceivers
* Configurable CAN termination resistors, which can be disabled via breakable jumpers
* Flexible power supply options
* Support of a wide choice of commonly used Integrated Development Environments (IDEs)
* Comprehensive free software libraries and examples for CAN communication

=Getting started=

This section will provide you with comprehensive information about the ESP32-CAN-X2 development board's key components, mechanical layout, power rating, & requirements. This detailed information helps you to use the board effectively and efficiently in your projects.

== Key Components of ESP32-CAN-X2 Development Board ==

Figure 1 given below indicates the important key components of the ESP32-CAN-X2 Development Board and their location on the board.

[[File:Development Board Key Components.png|Figure 1]]

=== Microcontroller ===

The ESP32-CAN-X2 Development Board is designed around the ESP32-S3-WROOM-1-N8R8 microcontroller in a 40-pin package. The connections between the development board and the microcontroller is straightforward, where the majority of GPIO pins are directly connected with the external headers, SV1 & SV2, and some pins are reserved internal connections between the board and CAN controllers. The internal connections between the microcontroller and CAN controllers are shown in the CAN controller heading given below. The microcontroller pin layout is shown in Figure 2 given below.

[[File:Microcontroller pin layout.png|Figure 2]]

=== External Connection Header ===

External headers, SV1 & SV2, are the two other important components of this development board. SV1 is the left side dual row header and the SV2 is the right side dual row header. Both of these headers have 20 pins available for connection. These headers provide connections for GPIOs, power output, ground (GND), power input, and CAN communication pins. Both of these header pinouts have standard size, allowing users to connect them using jumper wires, a breadboard, or even solder wires permanently onto the development board. However, while doing the wire connection the customer must make sure that none of them get short circuit. The details regarding the pin's names, numbers, outputs, and functions are given in the Board Pinout section below.

=== CAN Controllers ===

The MCP2515 external connected CAN communication controller, and ESP-32 built-in CAN communication controller are two other main components of this development board.

The MCP2515, operating as the second external CAN controller in this development board, is a specialized component designed for Controller Area Network (CAN) applications. Its features include:

* Implements CAN V2.0B at up to 1 Mb/s.
* High-Speed SPI Interface (10 MHz)
* Interrupt Output Pin with selectable enables
* Multiple receive and transmit buffers
* Low-Power CMOS Technology: - 5 mA active current (typical), 1 μA standby current
 
The internal CAN controller also works at CAN V2.0. The internal CAN supports two message formats:

* Base frame format (11-bit ID)
* Extended frame format (29-bit ID)
 
'''Internal pinout connection between the CAN controllers and ESP32'''

* CAN 1: This is a built-in CAN controller and its RX is connected to IO6 of the microcontroller and TX is connected to IO7 of the microcontroller. The connections are shown in Figure 3 given below
* CAN 2: This is the externally connected controller and its CS, MOSI, CLK, and MISO are connected at pin numbers 1O10, 1011, 1012, and 1O13 respectively. The connections are shown in Figure 3 given below

[[File:Internal connection.png|Figure 3]]

=== 6 pin JST-PH Connector ===

The ESP32-CAN-X2 development board provides an additional 6-pin connector header at the top of the board to supports CAN communication. This header makes wiring the device more convenient and robust. The CAN communication connection pinout details are given in the pinout section below.

=== USB-C Socket ===

The ESP32-CAN-X2 development board has one USB-C port. This port is used for multiple functions: it powers the board, allows programming, and facilitates serial communication both ways.
However, it is important to note that when powering the board through the USB-C port, please ensure the nominal voltage range is 6-20V and Vmax is 40V.

== Board Layout ==

Mechanical board outline physical dimensions:

* Width : 42.10 mm
* Length : 72 mm
 
The board top view is shown in the Figure 4 given below.

[[File:Board top view.png|Figure 4]]

== Power Ratings & Environmental Requirements ==

'''Power Options'''

The ESP32-CAN-X2 development board is flexible in its power input, and it provides multiple power input options. Power can either be supplied via the VIN pin, or via USB-C connector. Any voltage input either via USB or VIN is stepped down to 3.3 V via a voltage regulator.

'''Pin Voltage'''

All digital & analog pins on the ESP32-CAN-X2 development board are 3.3 V. Do not connect any higher voltage devices to any of the pins as it will risk damaging the board.

'''VIN Rating'''

The nominal input voltage rating for the development board is 6-20v, with a 40v max input. Please do not attempt to power the board with a voltage outside the recommended range.

'''Operating Current'''

The typical operating current of ESP32-CAN-X2 development board is 105mA and maximum operating current is 500mA ( peak, during transmission )

'''Power Consumption'''

The normal power consumption of the board is 330mW and peak power consumption is 1.65W

'''Operating Temperature'''

Temperate rating is -40°C to +85°C

=CAN bus information=

CAN, also known as Control area networking, is a serial communication protocol that is widely used in Automotive applications. CAN bus communication protocol utilizes differential signaling methods in which data is transferred as a voltage difference between High and low voltage. Can Bus communication provides various advantages over other communication methods which makes it the most important communication protocol in automotive. A few features are follows

'''Multimaster system'''

In CAN Bus communication, multiple controllers can act as a master, and multiple devices can act as a node. Each node can share data with other nodes via the CAN bus. In modern cars, there are more than 70 ECUs, and using CAN communication each ECU acts as a node and can transfer the data to the CAN bus, this data is then available to all the ECUs, and ECU can then check the data and decide whether to receive or ignore it.

For details, visit: https://www.csselectronics.com/pages/can-bus-simple-intro-tutorial

'''Lossless communication'''

CAN communication uses a bitwise arbitration method that avoids the contentions of data on the bus. When two nodes simultaneously try to send the data, then the node with the high priority ( lower identifier ) gets priority and continues transmitting. The identifier message can be 11-bit ( standard CAN ) or 29-bit ( extended CAN) in length.

For details, visit: https://dewesoft.com/blog/what-is-can-bus

'''Simple and cheap'''

The CAN communication between the ECUs is done through a single CAN system instead of direct complex analog signal lines which makes it extremely simple and reduces errors.

For details, visit: https://www.autopi.io/blog/can-bus-explained/

'''Errorless communication'''

CAN incorporates different built-in error detection mechanisms including cyclic redundancy checks (CRC), and frame check sequences (FCS) to detect errors during data transmission.

'''CAN network types'''
 
Prominent CAN network types are as follows.

* High-speed CAN bus ( Supports bit rates between 40 kbit/s and 1 Mbit/s )
* Low-Speed CAN bus ( Supports bit rates between 40 kbit/s and 125 kbit/s )
* CAN FD ( Supports bit rates between 1 Mbps to 8 Mbps )
 
For details, visit:https://dewesoft.com/blog/what-is-can-bus

'''Data transmission'''

In CAN, data is transferred between two nodes in messages known as CAN frames. There are four types of CAN frames.
* Data frame ( Used to transfer data between two node )
* Remote frame ( request data from other node )
* Error frame ( report errors )
* Overload frame ( report overload )
 
For details, visit:https://www.autopi.io/blog/can-bus-explained/

== CAN Termination ==

CAN termination is a process of terminating the CAN bus to prevent the signal reflection at the end of the bus and to ensure the correct DC level of the bus. The CAN BUS is bidirectional, and both ends of the bus must be properly terminated to prevent errors in communication. CAN termination is achieved by placing the termination resistance, which is normally 120 ohm, that matches the nominal resistance of the cable. ISO 11898 requires normally required CAN BUS cable of impedance 120 ohm; therefore, the CAN 120 ohm resistance is used for CAN termination. However, while doing the CAN termination, it must be kept in mind that the nodes from the far two ends of the cable only require termination resistors.

Figure 5 given below explain the CAN termination.

[[File:CAN BUS TERMINATION.png]]

Note :The low-speed CAN, single wire CAN, may not require the CAN bus termination.

'''How to enable & disable CAN termination in ESP-32-X2 ?'''

The ESP-32-X2 development board has given two separate CAN termination pads at the top of the development board adjacent to the 6-PIN CAN communication header. The CAN termination jumpers are shown in the figure 6 given below.

[[File:CAN BUS TERMINATION DISABLE JUMPERS.png]]

* Enable termination : In ESP-32-X2 development board, CAN termination is enabled by default.
* Disable termination : Scratch the copper trace between the pads, TERM1 & TERM2.
* Re-enable termination : Re-solder the traces between the pads

Note : Proper termination is necessary for ensuring errorless communication and signal integrity. Please follow the above given instruction carefully.

=Board Pinout=

The ESP32-CAN-X2 board has 40 pins across its two headers, SV1 & SV2 headers, and a 6-pin header at the top. This guide explains the pin functionalities of the board. The pin configuration of development board shown in Figure 7 given below.

[[File:Pin Configuration 1.png|Figure 7]]

'''Left Header (SV1) Pinout (Top to Bottom)'''

The pin count start from the top of the left header, and the pin details are as following :

{| class="wikitable"
|+
|-
! Pin !! Function !! Description
|-
| 1 || CAN1H/2.7D || high-level signal for the first CAN channel.
|-
| 2 || CAN1L/2.7D || low-level signal for the first CAN channel
|-
| 3 || CAN2H/2.7C || high-level signal for the second CAN channel
|-
| 4 || CAN2L/2.7C || low-level signal for the second CAN channel
|-
| 5 || RX Pin || USART RX
|-
| 6 || TX Pin || USART TX
|-
| 7-20|| GPIO Pins || GPIO's
|-
|}

'''Right Header (SV2) Pinout (Bottom to Top )'''

The pin count start from bottom to top and details are as following :

{| class="wikitable"
|+
|-
! Pin !! Function !! Description
|-
| 1-11 || GPIO Pins || GPIO's
|-
| 12-13 || 3.3V || 3.3 Voltage Output
|-
| 14-15 || 5V || 5 Voltage Output
|-
| 16-18 || GND || Ground
|-
| 19-20 || 12 Vin || 12 Voltage Input
|}

'''Top Header Pinout'''

The header supports CAN communication. Pin count start at the left viewing the board from the top. Pinout configuration of header is shown in Figure 8 given below.

[[File:6 PIN HEADER (1).png|Figure 8]]
* '''Note:''' Color codes on the provided pigtail may not match documentation.

{| class="wikitable"
|+
|-
! Pin !! Function !! Description
|-
| 1 || CAN1L/2.7A || low-level signal for the first CAN channel
|-
| 2 || CAN2L/2.7B || low-level signal for the second CAN channel
|-
| 3 || CAN2H/2.7B || high-level signal for the second CAN channel
|-
| 4 || GND || Ground
|-
| 5 || CAN1H/2.7A || high-level signal for the first CAN channel
|-
| 6 || +12V_ Aux || 6-12v power supply
|}

=Flashing Firmware=

Firmware flashing in this development board is straightforward. The following components are required for firmware flashings.

'''Hardware Components'''

* USB-C cable
* Computer running Windows, Linux, or macOS
 

'''Software Components'''

* Updated Arduino IDE to compile code for ESP-32-X2.
* Update Mu Editor from codewith.mu
 
Note : Link to download Arduino IDE : https://www.arduino.cc/en/software || Link to download Mu Editor : codewith.mu

== Step by step instruction for Arduino IDE==

===Sample Arduino Project===
https://github.com/autosportlabs/ESP32-CAN-X2

Step-by-step instructions for flashing ESP-32-X2 are as follows.

'''Install ESP-32-X2 Board Support:'''

Adding ESP-32-X2 in Arduino Ide is a single-time process and its steps are as follows.

* Open Arduino Ide
* Go to File > Preferences
 

[[File:Flashing1.png| Figure 7|800px]]

* Add the below given Json URL in the Additional board manager URL

Json URL : https://espressif.github.io/arduino-esp32/package_esp32_index.json
 
[[File:ESPBSP1.png|Figure 8|800px]]

* Go to Tools > Board > Boards Manager
 

[[File:Flashing3.png|Figure 9|800px]]

* In the Board Manager search bar, type ESP-32, search for esp32 by Espressif and click on install to install the board
 
[[File:ESPBSP2.png|Figure 10|800px]]

* After installing, click on Tool > Boards and select AutosportLabs ESP32-CAN-X2
 
'''Flashing'''

* Connect the ESP-32-X2 board to your computer using a USB-C cable with your Arduino IDE open

* Select AutosportLabs ESP32-CAN-X2 in Tools > Board menu

* Go to Tools > Port and select the COM port to which ESP-32-X2 is connected.

[[File:ArduinoFlashing3.png|Figure 11|800px]]
 
Note : If you don’t see the COM Port in your Arduino IDE, you need to install the CP210x USB to UART Bridge VCP Drivers: https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers
 

* Write your firmware code or add an existing sketch that you want to upload to your custom board.

* Go to Sketch > Click upload to compile and upload the code

* After successful uploading, you should see a “Done uploading.” message at the bottom console. This console will also show error messages if there is any error.

[[File:ArduinoFlashing4...png|Figure 12|800px]]

If any issues occur during upload, double-check the board selection, COM port, and your code for errors.
<be>

===Importing Libraries in Arduino IDE===

* To Install Libraries for ESP32-CAN-X2 like mcp_canbus or mcp2515
* Go to Sketch > Include Library > Manage LibrarieSs

[[File:Arduino IDE Library 1.png]]

* Type and find the desired library like mcp_canbus by Longan Labs
* Search and Install the library

[[File:Arduino IDE Library 2...png]]

== Step-by-step instruction for CircuitPython==
===Sample CircuitPython code===
https://github.com/autosportlabs/ESP32-CAN-X2

'''Downloading ESP-32-X2 Board Support:''' 

Installing ESP-32-X2 is simple, please follow the steps given below :

* Go to circuitpython.org/board/autosportlabs_esp32_can_x2
Click on the browse S3 

[[File:CircuitpythonFlashing1.png|800px]] 

* Select the desired language 
 

[[File:CircuitpythonFlashing2.png|800px]]
* Download the latest .bin file
 

[[File:CircuitpythonFlashing4.png|800px]]

'''Prepare the ESP32 CAN X2 for Installation:''' 

* Connect the ESP-32-X2 board to your computer using a USB-C cable
* Press and hold the boot button on the development board.
* While holding the boot button, press and release the reset button once.
* Release the boot button to put the board into bootloader mode.
[[File:CircuitpythonFlashing5.png|800px]]

'''Connect to the Web Serial ESP Tool'''

* Go to : https://adafruit.github.io/Adafruit_WebSerial_ESPTool/
* Press the Connect button in the top right corner of the page.
* A pop-up will appear asking you to select the COM or Serial port.
* Look for an option with ESP32, JTAG Loader, SLAB, or FTDI in the name
 

[[File:CircuitpythonFlashing6.png|800px]]

'''Flash the Firmware'''

* Click on Choose the .bin file you downloaded.
* Ensure that the Offset box next to the file location is set to 0x0.
* After selecting the file, the button text will change to match your filename.
* Click the Program button to start flashing. A progress bar will appear, and after a minute or two, the firmware will be
written.

[[File:Circuytpython7.gif|800px]]

'''Exit Bootloader Mode'''
* Press the reset button to exit bootloader mode. Shortly, the CIRCUITPY drive will pop up.

'''Downloading and Installing Mu Editor'''
* Download and install the recommended Mu Editor from codewith.mu.
* When you first start Mu, you will be prompted to select your mode. Select CircuitPython.
 
[[File:Mudownload.png|800px]]

* In Mu editor, click the Load button in the button bar, navigate to the CIRCUITPY drive, and choose code.py.
 
[[File:MU2.png|800px]]

'''Note :''' The CIRCUITPY drive is where your code and necessary libraries will reside. With a fresh CircuitPython install, the CIRCUITPY drive will contain a code.py file with print("Hello World!") and an empty lib folder. If your CIRCUITPY drive does not have a code.py file, create one and save it to the drive. CircuitPython automatically executes the code in code.py when the board starts up or resets. Do not press reset immediately after saving your code it will corrupt the drive and you may lose your code.

* Enter your code into the editor and save the code.py file on the CIRCUITPY drive.
 

[[File:MU3.png|800px]]

'''Congratulations!''' You have just run your first CircuitPython program.

=== Importing Libraries in Circuitpython ===

Importing libraries in Circuitpython is straightforward. For installing Libraries in Circuitpython, please follow the steps given below :
* Go to https://circuitpython.org/libraries and download the bundle for version 9.xx.
'''Note:''' The version of the bundle should be the same that you are using.
 

[[File:Mu4.png|800px]]

* Extract the zip file.
* Find the lib file where you can find your desired library.
* Copy that library folder or .mpy file and paste it to the lib folder in CIRCUITPY drive
 

[[File:Mueditor Library.gif|800px]]

=Bolt-ons=
Autosport Labs provides various add-on boards, known as "bolt-ons" for ESP32-CAN-X2. For Further details regarding bolt-on. Please click on the specific bolt-on links given below
* [https://wiki.autosportlabs.com/Bolt-on#GPS_Bolt-on GPS Bolt-on]

ESP32-CAN-X2

2024-11-05T19:42:35Z

Ddimensia: /* Board Pinout */ Fixed header identifiers on pinout

=Introduction=

ESP32-CAN-X2 is an ESP32-based development board specifically designed for CAN communication. This board has all the features of a modern ESP32 development board, integrated Wi-Fi and Bluetooth, along with the extended CAN controller. Autosport Labs has specifically designed it for CAN communication along with fast processing and computation options.

This is a complete how-to-use guide and this user guide will describe each and every step to use the board and harness the maximum potential of the board.

=Features=

Features of ESP32-CAN-X2 development board:

* Based on ESP32-S3-WROOM-1-N8R8 microcontroller powerful dual-core Xtensa LX6 CPU running at up to 240 MHz.
* 384 KB ROM, 512 KB SRAM, 16 KB SRAM in RTC, 8 MB PSRAM
* Two LED’s : Power LED and user defined LED1
* Integrated Wi-Fi (802.11b/g/n) and Bluetooth capabilities
* Reset and Boot push button
* USB-C type socket for flashing, and power supply
* Integrated antenna for long range communication
* Additional CAN communication controller CAN using MCP2515
* 6-pin header is strategically positioned at the top for CAN communication
* Easy-to-interface programming. Required no external debugger for flashing
* Integrated CAN transceivers
* Configurable CAN termination resistors, which can be disabled via breakable jumpers
* Flexible power supply options
* Support of a wide choice of commonly used Integrated Development Environments (IDEs)
* Comprehensive free software libraries and examples for CAN communication

=Getting started=

This section will provide you with comprehensive information about the ESP32-CAN-X2 development board's key components, mechanical layout, power rating, & requirements. This detailed information helps you to use the board effectively and efficiently in your projects.

== Key Components of ESP32-CAN-X2 Development Board ==

Figure 1 given below indicates the important key components of the ESP32-CAN-X2 Development Board and their location on the board.

[[File:Development Board Key Components.png|Figure 1]]

=== Microcontroller ===

The ESP32-CAN-X2 Development Board is designed around the ESP32-S3-WROOM-1-N8R8 microcontroller in a 40-pin package. The connections between the development board and the microcontroller is straightforward, where the majority of GPIO pins are directly connected with the external headers, SV1 & SV2, and some pins are reserved internal connections between the board and CAN controllers. The internal connections between the microcontroller and CAN controllers are shown in the CAN controller heading given below. The microcontroller pin layout is shown in Figure 2 given below.

[[File:Microcontroller pin layout.png|Figure 2]]

=== External Connection Header ===

External headers, SV1 & SV2, are the two other important components of this development board. SV1 is the left side dual row header and the SV2 is the right side dual row header. Both of these headers have 20 pins available for connection. These headers provide connections for GPIOs, power output, ground (GND), power input, and CAN communication pins. Both of these header pinouts have standard size, allowing users to connect them using jumper wires, a breadboard, or even solder wires permanently onto the development board. However, while doing the wire connection the customer must make sure that none of them get short circuit. The details regarding the pin's names, numbers, outputs, and functions are given in the Board Pinout section below.

=== CAN Controllers ===

The MCP2515 external connected CAN communication controller, and ESP-32 built-in CAN communication controller are two other main components of this development board.

The MCP2515, operating as the second external CAN controller in this development board, is a specialized component designed for Controller Area Network (CAN) applications. Its features include:

* Implements CAN V2.0B at up to 1 Mb/s.
* High-Speed SPI Interface (10 MHz)
* Interrupt Output Pin with selectable enables
* Multiple receive and transmit buffers
* Low-Power CMOS Technology: - 5 mA active current (typical), 1 μA standby current
 
The internal CAN controller also works at CAN V2.0. The internal CAN supports two message formats:

* Base frame format (11-bit ID)
* Extended frame format (29-bit ID)
 
'''Internal pinout connection between the CAN controllers and ESP32'''

* CAN 1: This is a built-in CAN controller and its RX is connected to IO6 of the microcontroller and TX is connected to IO7 of the microcontroller. The connections are shown in Figure 3 given below
* CAN 2: This is the externally connected controller and its CS, MOSI, CLK, and MISO are connected at pin numbers 1O10, 1011, 1012, and 1O13 respectively. The connections are shown in Figure 3 given below

[[File:Internal connection.png|Figure 3]]

=== 6 pin JST-PH Connector ===

The ESP32-CAN-X2 development board provides an additional 6-pin connector header at the top of the board to supports CAN communication. This header makes wiring the device more convenient and robust. The CAN communication connection pinout details are given in the pinout section below.

=== USB-C Socket ===

The ESP32-CAN-X2 development board has one USB-C port. This port is used for multiple functions: it powers the board, allows programming, and facilitates serial communication both ways.
However, it is important to note that when powering the board through the USB-C port, please ensure the nominal voltage range is 6-20V and Vmax is 40V.

== Board Layout ==

Mechanical board outline physical dimensions:

* Width : 42.10 mm
* Length : 72 mm
 
The board top view is shown in the Figure 4 given below.

[[File:Board top view.png|Figure 4]]

== Power Ratings & Environmental Requirements ==

'''Power Options'''

The ESP32-CAN-X2 development board is flexible in its power input, and it provides multiple power input options. Power can either be supplied via the VIN pin, or via USB-C connector. Any voltage input either via USB or VIN is stepped down to 3.3 V via a voltage regulator.

'''Pin Voltage'''

All digital & analog pins on the ESP32-CAN-X2 development board are 3.3 V. Do not connect any higher voltage devices to any of the pins as it will risk damaging the board.

'''VIN Rating'''

The nominal input voltage rating for the development board is 6-20v, with a 40v max input. Please do not attempt to power the board with a voltage outside the recommended range.

'''Operating Current'''

The typical operating current of ESP32-CAN-X2 development board is 105mA and maximum operating current is 500mA ( peak, during transmission )

'''Power Consumption'''

The normal power consumption of the board is 330mW and peak power consumption is 1.65W

'''Operating Temperature'''

Temperate rating is -40°C to +85°C

=CAN bus information=

CAN, also known as Control area networking, is a serial communication protocol that is widely used in Automotive applications. CAN bus communication protocol utilizes differential signaling methods in which data is transferred as a voltage difference between High and low voltage. Can Bus communication provides various advantages over other communication methods which makes it the most important communication protocol in automotive. A few features are follows

'''Multimaster system'''

In CAN Bus communication, multiple controllers can act as a master, and multiple devices can act as a node. Each node can share data with other nodes via the CAN bus. In modern cars, there are more than 70 ECUs, and using CAN communication each ECU acts as a node and can transfer the data to the CAN bus, this data is then available to all the ECUs, and ECU can then check the data and decide whether to receive or ignore it.

For details, visit: https://www.csselectronics.com/pages/can-bus-simple-intro-tutorial

'''Lossless communication'''

CAN communication uses a bitwise arbitration method that avoids the contentions of data on the bus. When two nodes simultaneously try to send the data, then the node with the high priority ( lower identifier ) gets priority and continues transmitting. The identifier message can be 11-bit ( standard CAN ) or 29-bit ( extended CAN) in length.

For details, visit: https://dewesoft.com/blog/what-is-can-bus

'''Simple and cheap'''

The CAN communication between the ECUs is done through a single CAN system instead of direct complex analog signal lines which makes it extremely simple and reduces errors.

For details, visit: https://www.autopi.io/blog/can-bus-explained/

'''Errorless communication'''

CAN incorporates different built-in error detection mechanisms including cyclic redundancy checks (CRC), and frame check sequences (FCS) to detect errors during data transmission.

'''CAN network types'''
 
Prominent CAN network types are as follows.

* High-speed CAN bus ( Supports bit rates between 40 kbit/s and 1 Mbit/s )
* Low-Speed CAN bus ( Supports bit rates between 40 kbit/s and 125 kbit/s )
* CAN FD ( Supports bit rates between 1 Mbps to 8 Mbps )
 
For details, visit:https://dewesoft.com/blog/what-is-can-bus

'''Data transmission'''

In CAN, data is transferred between two nodes in messages known as CAN frames. There are four types of CAN frames.
* Data frame ( Used to transfer data between two node )
* Remote frame ( request data from other node )
* Error frame ( report errors )
* Overload frame ( report overload )
 
For details, visit:https://www.autopi.io/blog/can-bus-explained/

== CAN Termination ==

CAN termination is a process of terminating the CAN bus to prevent the signal reflection at the end of the bus and to ensure the correct DC level of the bus. The CAN BUS is bidirectional, and both ends of the bus must be properly terminated to prevent errors in communication. CAN termination is achieved by placing the termination resistance, which is normally 120 ohm, that matches the nominal resistance of the cable. ISO 11898 requires normally required CAN BUS cable of impedance 120 ohm; therefore, the CAN 120 ohm resistance is used for CAN termination. However, while doing the CAN termination, it must be kept in mind that the nodes from the far two ends of the cable only require termination resistors.

Figure 5 given below explain the CAN termination.

[[File:CAN BUS TERMINATION.png]]

Note :The low-speed CAN, single wire CAN, may not require the CAN bus termination.

'''How to enable & disable CAN termination in ESP-32-X2 ?'''

The ESP-32-X2 development board has given two separate CAN termination pads at the top of the development board adjacent to the 6-PIN CAN communication header. The CAN termination jumpers are shown in the figure 6 given below.

[[File:CAN BUS TERMINATION DISABLE JUMPERS.png]]

* Enable termination : In ESP-32-X2 development board, CAN termination is enabled by default.
* Disable termination : Scratch the copper trace between the pads, TERM1 & TERM2.
* Re-enable termination : Re-solder the traces between the pads

Note : Proper termination is necessary for ensuring errorless communication and signal integrity. Please follow the above given instruction carefully.

=Board Pinout=

The ESP32-CAN-X2 board has 40 pins across its two headers, SV1 & SV2 headers, and a 6-pin header at the top. This guide explains the pin functionalities of the board. The pin configuration of development board shown in Figure 7 given below.

[[File:Pin Configuration 1.png|Figure 7]]

'''Left Header (SV1) Pinout (Top to Bottom)'''

The pin count start from the top of the left header, and the pin details are as following :

{| class="wikitable"
|+
|-
! Pin !! Function !! Description
|-
| 1 || CAN1H/2.7D || high-level signal for the first CAN channel.
|-
| 2 || CAN1L/2.7D || low-level signal for the first CAN channel
|-
| 3 || CAN2H/2.7C || high-level signal for the second CAN channel
|-
| 4 || CAN2L/2.7C || low-level signal for the second CAN channel
|-
| 5 || RX Pin || USART RX
|-
| 6 || TX Pin || USART TX
|-
| 7-20|| GPIO Pins || GPIO's
|-
|}

'''Right Header (SV2) Pinout (Bottom to Top )'''

The pin count start from bottom to top and details are as following :

{| class="wikitable"
|+
|-
! Pin !! Function !! Description
|-
| 1-11 || GPIO Pins || GPIO's
|-
| 12-13 || Vin || Voltage Input
|-
| 14-15 || 5V || 5 Voltage Output
|-
| 16-18 || GND || Ground
|-
| 19-20 || 12 Vin || 12 Voltage Input
|}

'''Top Header Pinout'''

The header supports CAN communication. Pin count start at the left viewing the board from the top. Pinout configuration of header is shown in Figure 8 given below.

[[File:6 PIN HEADER (1).png|Figure 8]]
* '''Note:''' Color codes on the provided pigtail may not match documentation.

{| class="wikitable"
|+
|-
! Pin !! Function !! Description
|-
| 1 || CAN1L/2.7A || low-level signal for the first CAN channel
|-
| 2 || CAN2L/2.7B || low-level signal for the second CAN channel
|-
| 3 || CAN2H/2.7B || high-level signal for the second CAN channel
|-
| 4 || GND || Ground
|-
| 5 || CAN1H/2.7A || high-level signal for the first CAN channel
|-
| 6 || +12V_ Aux || 6-12v power supply
|}

=Flashing Firmware=

Firmware flashing in this development board is straightforward. The following components are required for firmware flashings.

'''Hardware Components'''

* USB-C cable
* Computer running Windows, Linux, or macOS
 

'''Software Components'''

* Updated Arduino IDE to compile code for ESP-32-X2.
* Update Mu Editor from codewith.mu
 
Note : Link to download Arduino IDE : https://www.arduino.cc/en/software || Link to download Mu Editor : codewith.mu

== Step by step instruction for Arduino IDE==

===Sample Arduino Project===
https://github.com/autosportlabs/ESP32-CAN-X2

Step-by-step instructions for flashing ESP-32-X2 are as follows.

'''Install ESP-32-X2 Board Support:'''

Adding ESP-32-X2 in Arduino Ide is a single-time process and its steps are as follows.

* Open Arduino Ide
* Go to File > Preferences
 

[[File:Flashing1.png| Figure 7|800px]]

* Add the below given Json URL in the Additional board manager URL

Json URL : https://espressif.github.io/arduino-esp32/package_esp32_index.json
 
[[File:ESPBSP1.png|Figure 8|800px]]

* Go to Tools > Board > Boards Manager
 

[[File:Flashing3.png|Figure 9|800px]]

* In the Board Manager search bar, type ESP-32, search for esp32 by Espressif and click on install to install the board
 
[[File:ESPBSP2.png|Figure 10|800px]]

* After installing, click on Tool > Boards and select AutosportLabs ESP32-CAN-X2
 
'''Flashing'''

* Connect the ESP-32-X2 board to your computer using a USB-C cable with your Arduino IDE open

* Select AutosportLabs ESP32-CAN-X2 in Tools > Board menu

* Go to Tools > Port and select the COM port to which ESP-32-X2 is connected.

[[File:ArduinoFlashing3.png|Figure 11|800px]]
 
Note : If you don’t see the COM Port in your Arduino IDE, you need to install the CP210x USB to UART Bridge VCP Drivers: https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers
 

* Write your firmware code or add an existing sketch that you want to upload to your custom board.

* Go to Sketch > Click upload to compile and upload the code

* After successful uploading, you should see a “Done uploading.” message at the bottom console. This console will also show error messages if there is any error.

[[File:ArduinoFlashing4...png|Figure 12|800px]]

If any issues occur during upload, double-check the board selection, COM port, and your code for errors.
<be>

===Importing Libraries in Arduino IDE===

* To Install Libraries for ESP32-CAN-X2 like mcp_canbus or mcp2515
* Go to Sketch > Include Library > Manage LibrarieSs

[[File:Arduino IDE Library 1.png]]

* Type and find the desired library like mcp_canbus by Longan Labs
* Search and Install the library

[[File:Arduino IDE Library 2...png]]

== Step-by-step instruction for CircuitPython==
===Sample CircuitPython code===
https://github.com/autosportlabs/ESP32-CAN-X2

'''Downloading ESP-32-X2 Board Support:''' 

Installing ESP-32-X2 is simple, please follow the steps given below :

* Go to circuitpython.org/board/autosportlabs_esp32_can_x2
Click on the browse S3 

[[File:CircuitpythonFlashing1.png|800px]] 

* Select the desired language 
 

[[File:CircuitpythonFlashing2.png|800px]]
* Download the latest .bin file
 

[[File:CircuitpythonFlashing4.png|800px]]

'''Prepare the ESP32 CAN X2 for Installation:''' 

* Connect the ESP-32-X2 board to your computer using a USB-C cable
* Press and hold the boot button on the development board.
* While holding the boot button, press and release the reset button once.
* Release the boot button to put the board into bootloader mode.
[[File:CircuitpythonFlashing5.png|800px]]

'''Connect to the Web Serial ESP Tool'''

* Go to : https://adafruit.github.io/Adafruit_WebSerial_ESPTool/
* Press the Connect button in the top right corner of the page.
* A pop-up will appear asking you to select the COM or Serial port.
* Look for an option with ESP32, JTAG Loader, SLAB, or FTDI in the name
 

[[File:CircuitpythonFlashing6.png|800px]]

'''Flash the Firmware'''

* Click on Choose the .bin file you downloaded.
* Ensure that the Offset box next to the file location is set to 0x0.
* After selecting the file, the button text will change to match your filename.
* Click the Program button to start flashing. A progress bar will appear, and after a minute or two, the firmware will be
written.

[[File:Circuytpython7.gif|800px]]

'''Exit Bootloader Mode'''
* Press the reset button to exit bootloader mode. Shortly, the CIRCUITPY drive will pop up.

'''Downloading and Installing Mu Editor'''
* Download and install the recommended Mu Editor from codewith.mu.
* When you first start Mu, you will be prompted to select your mode. Select CircuitPython.
 
[[File:Mudownload.png|800px]]

* In Mu editor, click the Load button in the button bar, navigate to the CIRCUITPY drive, and choose code.py.
 
[[File:MU2.png|800px]]

'''Note :''' The CIRCUITPY drive is where your code and necessary libraries will reside. With a fresh CircuitPython install, the CIRCUITPY drive will contain a code.py file with print("Hello World!") and an empty lib folder. If your CIRCUITPY drive does not have a code.py file, create one and save it to the drive. CircuitPython automatically executes the code in code.py when the board starts up or resets. Do not press reset immediately after saving your code it will corrupt the drive and you may lose your code.

* Enter your code into the editor and save the code.py file on the CIRCUITPY drive.
 

[[File:MU3.png|800px]]

'''Congratulations!''' You have just run your first CircuitPython program.

=== Importing Libraries in Circuitpython ===

Importing libraries in Circuitpython is straightforward. For installing Libraries in Circuitpython, please follow the steps given below :
* Go to https://circuitpython.org/libraries and download the bundle for version 9.xx.
'''Note:''' The version of the bundle should be the same that you are using.
 

[[File:Mu4.png|800px]]

* Extract the zip file.
* Find the lib file where you can find your desired library.
* Copy that library folder or .mpy file and paste it to the lib folder in CIRCUITPY drive
 

[[File:Mueditor Library.gif|800px]]

=Bolt-ons=
Autosport Labs provides various add-on boards, known as "bolt-ons" for ESP32-CAN-X2. For Further details regarding bolt-on. Please click on the specific bolt-on links given below
* [https://wiki.autosportlabs.com/Bolt-on#GPS_Bolt-on GPS Bolt-on]

RaceCapturePro Lua Scripting

2024-05-30T16:15:58Z

Ddimensia: /* sxRxButton() */

=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]]'''

The [https://www.lua.org/manual/5.1/ Lua Reference Manual] can be found on [https://www.lua.org/ Lua.org]

You can use [http://luaedit.sourceforge.net/ LuaEdit] to help you edit and debug your Lua code.

==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>

* '''Note''': There can only be one onTick() handler; if multiple are defined your script will not work properly.

=====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, maximum of 1000Hz.

* '''Note:''' actual tick rates may be slower based on the amount of processing time in your onTick() handler.

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

==Troubleshooting==
===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>

===Out of memory issues===
If you are seeing out of memory issues, try the following:

====Mark variables in your script as local====

Lua makes variables global by default, which is typically opposite of other programming languages. Since global variables consume more memory, try making variables declared in your function local:

<pre>
function addSomeNumbers()
local var1 = 3
local var2 = 5
return var1 + var2
end
</pre>

====Reduce extra comments, large string variable declaration and other bloat====
* Remove comments, shorten the size of any text strings you define - these all consume memory.

====Simplify your script====
* Reduce the number of variables at the top, and inline their usage in the script. This will help reduce the amount of global memory uses.
* Evaluate the functions you define. Sometimes it makes sense to combine your code into fewer functions, if it turns out you only call that function once. Other times, you may need to break out a function to save space, if you need that function repeatedly.

====Call the garbage collector periodically====
If your script is very close the limits of memory, regularly calling the garbage collector may help. Calling collectgarbage() in the onTick() is recommended:<pre>
function onTick()
collectgarbage()
-- other code --
end
</pre>

====Try a Lua minimizer====
Minimizing/Minifying your script will compact your script, at the expense of making it harder to read. You can try an [https://mothereff.in/lua-minifier online minifier] to see if that makes a difference.

* Since it makes your script harder to maintain, we recommend this as a last resort.

=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.
* When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground)

* '''Note''': RaceCapture/Pro MK1 has internal pull-up resistors to 5V.

===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: true = pushbutton is depressed; false = pushbutton is not depressed

==PWM / Analog Output functions==
'''PWM / Analog outputs only apply to RaceCapture/Pro MK1 and MK2''

===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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
*** Note: the last Analog input is connected to battery voltage:
**** Channel 7 on RaceCapture/Pro MK1 and MK2
****Channel 8 on RaceCapture/Pro MK3 and RaceCapture Apex
****Channel 0 on RaceCapture/Track MK1 / MK2
** 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 = X, 1 = Y, 2=Z, 3= Yaw, 4= Pitch, 5 = Roll)
* 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 = X, 1 = Y, 2=Z, 3= Yaw, 4= Pitch, 5 = Roll)
* 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

===getGpsSats()===
* params
** (none)
* returns
** The number of GPS satellites currently used in the 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>

===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

==Lap Statistics==

===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

===getPredTime()===
''as of 2.12.0 firmware''

Provides the current Predicted Lap time time as determined by the start/finish line configuration and measured by the attached GPS module. A training lap is required before the predicted time is valid.
* params
** (none)
* returns
** The current predicted time in decimal minutes / seconds

===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
** true if currently within the start/finish line target, false if outside

===resetLapStats()===
''since 2.16.0''

Resets Lap Statistics, including lap count, lap time, predictive time, and session time.
* params
** (none)
* returns
** (none)

==Time Functions==
===getTickCount()===
Returns the number of milliseconds since power-up.
* params
None
* returns
** The number of milliseconds since power-up

==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
** termination: 1 to enable termination, 0 to disable. Defaults to 1 (enabled) ''Only available on RaceCapture/Pro MK3 and RaceCapture/Apex. On other platforms this setting has no effect''.
* 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

==OBDII functions==
===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)

===setOBD2Delay( delayMs )===
Sets an additional delay in-between OBDII PID queries. Normally the system will query PIDs as fast as possible, in a [[RC_OBDII|round robin fashion]].

If the vehicle's ECU exhibits problems with the rate of querying, an additional delay can be added between queries to effectively slow down the queries.

* params
** The additional delay between PID queries, in ms
* returns
** none

==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 1000Hz.
* returns
** (none)

==SD Logging control==
The following functions control logging operations to the internal SD card.
* '''Note:''' Only SD card logging is controlled; External devices or apps connected to the telemetry stream are not affected by these commands.

===isLogging()===
Indicates if an SD card logging session is in progress
* params
** (none)
* returns
** 0 if not logging, non zero otherwise.

===startLogging()===
Begins a logging session to the SD card. If currently logging, this function has no effect.
* '''Note:''' If an error occurs during writing, the error indicator on the front panel, if provided, will illuminate.
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current SD card 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/3/Apex only) 
* 3 = Bluetooth port 
* 4 = Auxiliary / WiFi port (RaceCapture/Pro MK2)
* 5 = WiFi port
* 6 = External Auxiliary port (RaceCapture/Pro MK3 and RaceCapture/Apex only)

* '''Note''': We only recommend using the designated auxiliary port for your hardware model The other ports 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
** true if initialization succeeds

===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 or name )===
* First available in v2.9.0 ; retrieving by channel name available in v2.13.0
* Parameters
** Channel ID or name : if a number, matches on the channel ID as provided by the '''addChannel''' function. If string, matches on any current channel in the system.
* Returns
** (number) The current value of the channel if available, or '''nil''' if the value is not available. You should always check if the value is present before using it for other purposes, especially if the script's tick rate is high relative to the channel's sample rate.

* Examples:

--returns the virtual channel assigned to ID 1. Current value of channel is stored in val
val = getChannel(1)

--get the channel by name
rpm = getChannel("RPM")
if rpm ~= nil then
println("rpm channel: " ..rpm)
end

===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, in UTC. 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
** Minute
** Second
** Millisecond

==Dashboard Control==
===txButton()===
Simulates button press events for dashboard navigation and control. RaceCapture dashboard must be connected for function to have effect.
* params
** button_id: ID of button to transmit. 0 = left button;1 = right button;2 = ack/yes;3 = no
** state: State of button: 1 = pressed; 0 = not pressed
* returns
** (nothing)

==ShiftX2/3 control==
The following functions provide access to the [[ShiftX2]] or [[ShiftX3]] RGB sequential shift light. ''Available in firmware 2.15.0''

===sxSetConfig()===
Configures the connected ShiftX device. This must be called prior to any other configuration function calls. All parameters are optional; call with no parameters to use the default settings:
<pre>
sxSetConfig()
</pre>
* params
** orientation: 0 (normal, 7-segment display below bar graph); 1 (inverted, 7-segment display above bar graph). Defaut value: 0
** brightness: 0 (automatic brightness control with ambient light sensor; 1-100: brightness percentage. Default value: 0
** CAN bus: 0 (connected to CAN1); 1 (connected to CAN2). Default value: 1
** CAN base address: base CAN address to use. Default value: 931328)
** Auto brightness scaling: Amplification value to tune ambient light sensor. 0-255 value; Default value: 51
** Enable / Disable button events: true (Enable button event broadcast to app); false (Disable button event broadcast to app)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxCfgLinearGraph()===
Configures the the style and overall range for the linear graph.
* params
** Rendering Style: 0 (left->right); 1 (center); 2 (right->left)
** Linear Style: 0 (Smooth / interpolated); 1 (stepped)
** Low Range Threshold: The overall low range for the linear graph
** High Range Threshold: The overall high range for the linear graph (ignored if linear style = stepped)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetLinearThresh()===
Configure a threshold for the linear graph. Each threshold is identified by an ID, and thresholds are processed from low to high IDs. 5 thresholds can be defined.
* params
** Threshold Id: Id for threshold to set. (0-4). Lower IDs are evaluated first.
** Segment Length: 0 -> number of LEDs on linear graph. (Ignored if linear style = smooth)
** Threshold Value: Value where this threshold is activated
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxUpdateLinearGraph()===
Update the linear graph with the current sensor value. ShiftX will apply the previously configured thresholds to set bar graph length, color and flash.
* params
** Value: current value representing the linear graph
* returns
** (none)
===sxSetAlert()===
Direct set an alert indicator. For ShiftX3, ID0=Alert LED on right side; ID1=Alert LED on left side.
* params
** Alert ID: ID of alert (0 -> # of alert indicators)
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetAlertThresh()===
Configures an alert threshold. Up to 5 thresholds can be configured per alert indicator. Thresholds are evaluated by ID, from low to high.
* params
** Alert ID: Id of Alert (0 -> # of alert indicators)
** Threshold ID: Id for threshold to set. (0-4). Lower IDs are evaluated first.
** Threshold Value: Value where this threshold is activated
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxUpdateAlert()===
Updates the current value for the specified Alert. ShiftX will apply the previously configured thresholds to set color and flash.
* params
** Alert ID: Id of Alert (0 -> # of alert indicators)
** Value: current value representing the alert
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetDisplay()===
Directly sets the value of the 7 segment display.
* params
** Digit index (must be 0)
** Charater: 0-9. Can set ASCII value by offsetting the value by 48 (e.g. ASCII - 48)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetLed()===
Directly set any available LED on ShiftX
* params
** LED Index: 0 -> # of LEDs on device
** Number of LEDs to set: 0 -> # of LEDs on device (0 = set all remaining)
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxRxButton()===
* params
** (none)
* returns
** nil if no button presses are available; otherwise:
** button_id (ID of button. left button = 0, right button = 1, yes = 2, ok/no = 3)
** state: (0 = not pressed; 1 = pressed)
<pre>
local id, state = sxRxButton()
if id ~= nil then println('button ' ..id ..' state ' ..state) end
</pre>

==Helper Functions==
===calcGear()===
A convenience function to calculate the current gear of the vehicle. ''Available in firmware 2.15.0''

Variation 1: Use built in GPS speed channel and RPM channel named "RPM"
* params
** Tire Diameter: Tire diameter, in cm.
** Final Drive Ratio: The ratio of the final drive
** Gear 1 Ratio: Ratio of 1st gear
** Gear 2 Ratio: Ratio of 2nd gear (optional)
** Gear 3 Ratio: Ratio of 3rd gear (optional)
** Gear 4 Ratio: Ratio of 4th gear (optional)
** Gear 5 Ratio: Ratio of 5th gear (optional)
** Gear 6 Ratio: Ratio of 6th gear (optional)
* returns
** detected gear (1-6) or nil if no gear was detected
<pre>
local gear = calcGear(62.7, 3.45, 4.23, 2.52, 1.66, 1.22, 1.0, 0.8)
if gear ~= nil then println('gear: ' ..gear) end
</pre>

Variation 2: Specify Speed and RPM channel
* params
** Speed Channel name
** RPM Channel name
** Tire Diameter: Tire diameter, in cm.
** Final Drive Ratio: The ratio of the final drive
** Gear 1 Ratio: Ratio of 1st gear
** Gear 2 Ratio: Ratio of 2nd gear (optional)
** Gear 3 Ratio: Ratio of 3rd gear (optional)
** Gear 4 Ratio: Ratio of 4th gear (optional)
** Gear 5 Ratio: Ratio of 5th gear (optional)
** Gear 6 Ratio: Ratio of 6th gear (optional)
* returns
** detected gear (1-6) or nil if no gear was detected
<pre>
local gear = calcGear('Speed', 'RPM', 62.7, 3.45, 4.23, 2.52, 1.66, 1.22, 1.0, 0.8)
if gear ~= nil then println('gear: ' ..gear) end
</pre>

RaceCapturePro Lua Scripting

2024-01-01T21:22:46Z

Ddimensia: /* txButton() */

=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]]'''

The [https://www.lua.org/manual/5.1/ Lua Reference Manual] can be found on [https://www.lua.org/ Lua.org]

You can use [http://luaedit.sourceforge.net/ LuaEdit] to help you edit and debug your Lua code.

==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>

* '''Note''': There can only be one onTick() handler; if multiple are defined your script will not work properly.

=====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, maximum of 1000Hz.

* '''Note:''' actual tick rates may be slower based on the amount of processing time in your onTick() handler.

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

==Troubleshooting==
===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>

===Out of memory issues===
If you are seeing out of memory issues, try the following:

====Mark variables in your script as local====

Lua makes variables global by default, which is typically opposite of other programming languages. Since global variables consume more memory, try making variables declared in your function local:

<pre>
function addSomeNumbers()
local var1 = 3
local var2 = 5
return var1 + var2
end
</pre>

====Reduce extra comments, large string variable declaration and other bloat====
* Remove comments, shorten the size of any text strings you define - these all consume memory.

====Simplify your script====
* Reduce the number of variables at the top, and inline their usage in the script. This will help reduce the amount of global memory uses.
* Evaluate the functions you define. Sometimes it makes sense to combine your code into fewer functions, if it turns out you only call that function once. Other times, you may need to break out a function to save space, if you need that function repeatedly.

====Call the garbage collector periodically====
If your script is very close the limits of memory, regularly calling the garbage collector may help. Calling collectgarbage() in the onTick() is recommended:<pre>
function onTick()
collectgarbage()
-- other code --
end
</pre>

====Try a Lua minimizer====
Minimizing/Minifying your script will compact your script, at the expense of making it harder to read. You can try an [https://mothereff.in/lua-minifier online minifier] to see if that makes a difference.

* Since it makes your script harder to maintain, we recommend this as a last resort.

=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.
* When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground)

* '''Note''': RaceCapture/Pro MK1 has internal pull-up resistors to 5V.

===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: true = pushbutton is depressed; false = pushbutton is not depressed

==PWM / Analog Output functions==
'''PWM / Analog outputs only apply to RaceCapture/Pro MK1 and MK2''

===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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
*** Note: the last Analog input is connected to battery voltage:
**** Channel 7 on RaceCapture/Pro MK1 and MK2
****Channel 8 on RaceCapture/Pro MK3 and RaceCapture Apex
****Channel 0 on RaceCapture/Track MK1 / MK2
** 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 = X, 1 = Y, 2=Z, 3= Yaw, 4= Pitch, 5 = Roll)
* 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 = X, 1 = Y, 2=Z, 3= Yaw, 4= Pitch, 5 = Roll)
* 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

===getGpsSats()===
* params
** (none)
* returns
** The number of GPS satellites currently used in the 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>

===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

==Lap Statistics==

===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

===getPredTime()===
''as of 2.12.0 firmware''

Provides the current Predicted Lap time time as determined by the start/finish line configuration and measured by the attached GPS module. A training lap is required before the predicted time is valid.
* params
** (none)
* returns
** The current predicted time in decimal minutes / seconds

===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
** true if currently within the start/finish line target, false if outside

===resetLapStats()===
''since 2.16.0''

Resets Lap Statistics, including lap count, lap time, predictive time, and session time.
* params
** (none)
* returns
** (none)

==Time Functions==
===getTickCount()===
Returns the number of milliseconds since power-up.
* params
None
* returns
** The number of milliseconds since power-up

==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
** termination: 1 to enable termination, 0 to disable. Defaults to 1 (enabled) ''Only available on RaceCapture/Pro MK3 and RaceCapture/Apex. On other platforms this setting has no effect''.
* 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

==OBDII functions==
===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)

===setOBD2Delay( delayMs )===
Sets an additional delay in-between OBDII PID queries. Normally the system will query PIDs as fast as possible, in a [[RC_OBDII|round robin fashion]].

If the vehicle's ECU exhibits problems with the rate of querying, an additional delay can be added between queries to effectively slow down the queries.

* params
** The additional delay between PID queries, in ms
* returns
** none

==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 1000Hz.
* returns
** (none)

==SD Logging control==
The following functions control logging operations to the internal SD card.
* '''Note:''' Only SD card logging is controlled; External devices or apps connected to the telemetry stream are not affected by these commands.

===isLogging()===
Indicates if an SD card logging session is in progress
* params
** (none)
* returns
** 0 if not logging, non zero otherwise.

===startLogging()===
Begins a logging session to the SD card. If currently logging, this function has no effect.
* '''Note:''' If an error occurs during writing, the error indicator on the front panel, if provided, will illuminate.
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current SD card 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/3/Apex only) 
* 3 = Bluetooth port 
* 4 = Auxiliary / WiFi port (RaceCapture/Pro MK2)
* 5 = WiFi port
* 6 = External Auxiliary port (RaceCapture/Pro MK3 and RaceCapture/Apex only)

* '''Note''': We only recommend using the designated auxiliary port for your hardware model The other ports 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
** true if initialization succeeds

===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 or name )===
* First available in v2.9.0 ; retrieving by channel name available in v2.13.0
* Parameters
** Channel ID or name : if a number, matches on the channel ID as provided by the '''addChannel''' function. If string, matches on any current channel in the system.
* Returns
** (number) The current value of the channel if available, or '''nil''' if the value is not available. You should always check if the value is present before using it for other purposes, especially if the script's tick rate is high relative to the channel's sample rate.

* Examples:

--returns the virtual channel assigned to ID 1. Current value of channel is stored in val
val = getChannel(1)

--get the channel by name
rpm = getChannel("RPM")
if rpm ~= nil then
println("rpm channel: " ..rpm)
end

===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, in UTC. 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
** Minute
** Second
** Millisecond

==Dashboard Control==
===txButton()===
Simulates button press events for dashboard navigation and control. RaceCapture dashboard must be connected for function to have effect.
* params
** button_id: ID of button to transmit. 0 = left button;1 = right button;2 = ack/yes;3 = no
** state: State of button: 1 = pressed; 0 = not pressed
* returns
** (nothing)

==ShiftX2/3 control==
The following functions provide access to the [[ShiftX2]] or [[ShiftX3]] RGB sequential shift light. ''Available in firmware 2.15.0''

===sxSetConfig()===
Configures the connected ShiftX device. This must be called prior to any other configuration function calls. All parameters are optional; call with no parameters to use the default settings:
<pre>
sxSetConfig()
</pre>
* params
** orientation: 0 (normal, 7-segment display below bar graph); 1 (inverted, 7-segment display above bar graph). Defaut value: 0
** brightness: 0 (automatic brightness control with ambient light sensor; 1-100: brightness percentage. Default value: 0
** CAN bus: 0 (connected to CAN1); 1 (connected to CAN2). Default value: 1
** CAN base address: base CAN address to use. Default value: 931328)
** Auto brightness scaling: Amplification value to tune ambient light sensor. 0-255 value; Default value: 51
** Enable / Disable button events: true (Enable button event broadcast to app); false (Disable button event broadcast to app)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxCfgLinearGraph()===
Configures the the style and overall range for the linear graph.
* params
** Rendering Style: 0 (left->right); 1 (center); 2 (right->left)
** Linear Style: 0 (Smooth / interpolated); 1 (stepped)
** Low Range Threshold: The overall low range for the linear graph
** High Range Threshold: The overall high range for the linear graph (ignored if linear style = stepped)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetLinearThresh()===
Configure a threshold for the linear graph. Each threshold is identified by an ID, and thresholds are processed from low to high IDs. 5 thresholds can be defined.
* params
** Threshold Id: Id for threshold to set. (0-4). Lower IDs are evaluated first.
** Segment Length: 0 -> number of LEDs on linear graph. (Ignored if linear style = smooth)
** Threshold Value: Value where this threshold is activated
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxUpdateLinearGraph()===
Update the linear graph with the current sensor value. ShiftX will apply the previously configured thresholds to set bar graph length, color and flash.
* params
** Value: current value representing the linear graph
* returns
** (none)
===sxSetAlert()===
Direct set an alert indicator. For ShiftX3, ID0=Alert LED on right side; ID1=Alert LED on left side.
* params
** Alert ID: ID of alert (0 -> # of alert indicators)
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetAlertThresh()===
Configures an alert threshold. Up to 5 thresholds can be configured per alert indicator. Thresholds are evaluated by ID, from low to high.
* params
** Alert ID: Id of Alert (0 -> # of alert indicators)
** Threshold ID: Id for threshold to set. (0-4). Lower IDs are evaluated first.
** Threshold Value: Value where this threshold is activated
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxUpdateAlert()===
Updates the current value for the specified Alert. ShiftX will apply the previously configured thresholds to set color and flash.
* params
** Alert ID: Id of Alert (0 -> # of alert indicators)
** Value: current value representing the alert
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetDisplay()===
Directly sets the value of the 7 segment display.
* params
** Digit index (must be 0)
** Charater: 0-9. Can set ASCII value by offsetting the value by 48 (e.g. ASCII - 48)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetLed()===
Directly set any available LED on ShiftX
* params
** LED Index: 0 -> # of LEDs on device
** Number of LEDs to set: 0 -> # of LEDs on device (0 = set all remaining)
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxRxButton()===
* params
** (none)
* returns
** nil if no button presses are available; otherwise:
** button_id (ID of button. left button = 0, right button = 1)
** state: (0 = not pressed; 1 = pressed)
<pre>
local id, state = sxRxButton()
if id ~= nil then println('button ' ..id ..' state ' ..state) end
</pre>

==Helper Functions==
===calcGear()===
A convenience function to calculate the current gear of the vehicle. ''Available in firmware 2.15.0''

Variation 1: Use built in GPS speed channel and RPM channel named "RPM"
* params
** Tire Diameter: Tire diameter, in cm.
** Final Drive Ratio: The ratio of the final drive
** Gear 1 Ratio: Ratio of 1st gear
** Gear 2 Ratio: Ratio of 2nd gear (optional)
** Gear 3 Ratio: Ratio of 3rd gear (optional)
** Gear 4 Ratio: Ratio of 4th gear (optional)
** Gear 5 Ratio: Ratio of 5th gear (optional)
** Gear 6 Ratio: Ratio of 6th gear (optional)
* returns
** detected gear (1-6) or nil if no gear was detected
<pre>
local gear = calcGear(62.7, 3.45, 4.23, 2.52, 1.66, 1.22, 1.0, 0.8)
if gear ~= nil then println('gear: ' ..gear) end
</pre>

Variation 2: Specify Speed and RPM channel
* params
** Speed Channel name
** RPM Channel name
** Tire Diameter: Tire diameter, in cm.
** Final Drive Ratio: The ratio of the final drive
** Gear 1 Ratio: Ratio of 1st gear
** Gear 2 Ratio: Ratio of 2nd gear (optional)
** Gear 3 Ratio: Ratio of 3rd gear (optional)
** Gear 4 Ratio: Ratio of 4th gear (optional)
** Gear 5 Ratio: Ratio of 5th gear (optional)
** Gear 6 Ratio: Ratio of 6th gear (optional)
* returns
** detected gear (1-6) or nil if no gear was detected
<pre>
local gear = calcGear('Speed', 'RPM', 62.7, 3.45, 4.23, 2.52, 1.66, 1.22, 1.0, 0.8)
if gear ~= nil then println('gear: ' ..gear) end
</pre>

RaceCapturePro Lua Scripting

2024-01-01T21:22:26Z

Ddimensia: Updated button_id values to include yes/no.

=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]]'''

The [https://www.lua.org/manual/5.1/ Lua Reference Manual] can be found on [https://www.lua.org/ Lua.org]

You can use [http://luaedit.sourceforge.net/ LuaEdit] to help you edit and debug your Lua code.

==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>

* '''Note''': There can only be one onTick() handler; if multiple are defined your script will not work properly.

=====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, maximum of 1000Hz.

* '''Note:''' actual tick rates may be slower based on the amount of processing time in your onTick() handler.

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

==Troubleshooting==
===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>

===Out of memory issues===
If you are seeing out of memory issues, try the following:

====Mark variables in your script as local====

Lua makes variables global by default, which is typically opposite of other programming languages. Since global variables consume more memory, try making variables declared in your function local:

<pre>
function addSomeNumbers()
local var1 = 3
local var2 = 5
return var1 + var2
end
</pre>

====Reduce extra comments, large string variable declaration and other bloat====
* Remove comments, shorten the size of any text strings you define - these all consume memory.

====Simplify your script====
* Reduce the number of variables at the top, and inline their usage in the script. This will help reduce the amount of global memory uses.
* Evaluate the functions you define. Sometimes it makes sense to combine your code into fewer functions, if it turns out you only call that function once. Other times, you may need to break out a function to save space, if you need that function repeatedly.

====Call the garbage collector periodically====
If your script is very close the limits of memory, regularly calling the garbage collector may help. Calling collectgarbage() in the onTick() is recommended:<pre>
function onTick()
collectgarbage()
-- other code --
end
</pre>

====Try a Lua minimizer====
Minimizing/Minifying your script will compact your script, at the expense of making it harder to read. You can try an [https://mothereff.in/lua-minifier online minifier] to see if that makes a difference.

* Since it makes your script harder to maintain, we recommend this as a last resort.

=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.
* When the channel is configured as output, the channel reads 1 when the channel is activated (output transistor is connected to ground)

* '''Note''': RaceCapture/Pro MK1 has internal pull-up resistors to 5V.

===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: true = pushbutton is depressed; false = pushbutton is not depressed

==PWM / Analog Output functions==
'''PWM / Analog outputs only apply to RaceCapture/Pro MK1 and MK2''

===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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
** 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. Zero based, so first channel is 0, 2nd channel is 1, and so on.
*** Note: the last Analog input is connected to battery voltage:
**** Channel 7 on RaceCapture/Pro MK1 and MK2
****Channel 8 on RaceCapture/Pro MK3 and RaceCapture Apex
****Channel 0 on RaceCapture/Track MK1 / MK2
** 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 = X, 1 = Y, 2=Z, 3= Yaw, 4= Pitch, 5 = Roll)
* 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 = X, 1 = Y, 2=Z, 3= Yaw, 4= Pitch, 5 = Roll)
* 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

===getGpsSats()===
* params
** (none)
* returns
** The number of GPS satellites currently used in the 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>

===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

==Lap Statistics==

===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

===getPredTime()===
''as of 2.12.0 firmware''

Provides the current Predicted Lap time time as determined by the start/finish line configuration and measured by the attached GPS module. A training lap is required before the predicted time is valid.
* params
** (none)
* returns
** The current predicted time in decimal minutes / seconds

===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
** true if currently within the start/finish line target, false if outside

===resetLapStats()===
''since 2.16.0''

Resets Lap Statistics, including lap count, lap time, predictive time, and session time.
* params
** (none)
* returns
** (none)

==Time Functions==
===getTickCount()===
Returns the number of milliseconds since power-up.
* params
None
* returns
** The number of milliseconds since power-up

==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
** termination: 1 to enable termination, 0 to disable. Defaults to 1 (enabled) ''Only available on RaceCapture/Pro MK3 and RaceCapture/Apex. On other platforms this setting has no effect''.
* 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

==OBDII functions==
===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)

===setOBD2Delay( delayMs )===
Sets an additional delay in-between OBDII PID queries. Normally the system will query PIDs as fast as possible, in a [[RC_OBDII|round robin fashion]].

If the vehicle's ECU exhibits problems with the rate of querying, an additional delay can be added between queries to effectively slow down the queries.

* params
** The additional delay between PID queries, in ms
* returns
** none

==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 1000Hz.
* returns
** (none)

==SD Logging control==
The following functions control logging operations to the internal SD card.
* '''Note:''' Only SD card logging is controlled; External devices or apps connected to the telemetry stream are not affected by these commands.

===isLogging()===
Indicates if an SD card logging session is in progress
* params
** (none)
* returns
** 0 if not logging, non zero otherwise.

===startLogging()===
Begins a logging session to the SD card. If currently logging, this function has no effect.
* '''Note:''' If an error occurs during writing, the error indicator on the front panel, if provided, will illuminate.
* params
** (none)
* returns
** (none)

===stopLogging()===
Stops the current SD card 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/3/Apex only) 
* 3 = Bluetooth port 
* 4 = Auxiliary / WiFi port (RaceCapture/Pro MK2)
* 5 = WiFi port
* 6 = External Auxiliary port (RaceCapture/Pro MK3 and RaceCapture/Apex only)

* '''Note''': We only recommend using the designated auxiliary port for your hardware model The other ports 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
** true if initialization succeeds

===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 or name )===
* First available in v2.9.0 ; retrieving by channel name available in v2.13.0
* Parameters
** Channel ID or name : if a number, matches on the channel ID as provided by the '''addChannel''' function. If string, matches on any current channel in the system.
* Returns
** (number) The current value of the channel if available, or '''nil''' if the value is not available. You should always check if the value is present before using it for other purposes, especially if the script's tick rate is high relative to the channel's sample rate.

* Examples:

--returns the virtual channel assigned to ID 1. Current value of channel is stored in val
val = getChannel(1)

--get the channel by name
rpm = getChannel("RPM")
if rpm ~= nil then
println("rpm channel: " ..rpm)
end

===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, in UTC. 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
** Minute
** Second
** Millisecond

==Dashboard Control==
===txButton()===
Simulates button press events for dashboard navigation and control. RaceCapture dashboard must be connected for function to have effect.
* params
** button_id: ID of button to transmit. 0 = left button;1 = right button;2 = Ack/Yes;3 = No
** state: State of button: 1 = pressed; 0 = not pressed
* returns
** (nothing)

==ShiftX2/3 control==
The following functions provide access to the [[ShiftX2]] or [[ShiftX3]] RGB sequential shift light. ''Available in firmware 2.15.0''

===sxSetConfig()===
Configures the connected ShiftX device. This must be called prior to any other configuration function calls. All parameters are optional; call with no parameters to use the default settings:
<pre>
sxSetConfig()
</pre>
* params
** orientation: 0 (normal, 7-segment display below bar graph); 1 (inverted, 7-segment display above bar graph). Defaut value: 0
** brightness: 0 (automatic brightness control with ambient light sensor; 1-100: brightness percentage. Default value: 0
** CAN bus: 0 (connected to CAN1); 1 (connected to CAN2). Default value: 1
** CAN base address: base CAN address to use. Default value: 931328)
** Auto brightness scaling: Amplification value to tune ambient light sensor. 0-255 value; Default value: 51
** Enable / Disable button events: true (Enable button event broadcast to app); false (Disable button event broadcast to app)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxCfgLinearGraph()===
Configures the the style and overall range for the linear graph.
* params
** Rendering Style: 0 (left->right); 1 (center); 2 (right->left)
** Linear Style: 0 (Smooth / interpolated); 1 (stepped)
** Low Range Threshold: The overall low range for the linear graph
** High Range Threshold: The overall high range for the linear graph (ignored if linear style = stepped)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetLinearThresh()===
Configure a threshold for the linear graph. Each threshold is identified by an ID, and thresholds are processed from low to high IDs. 5 thresholds can be defined.
* params
** Threshold Id: Id for threshold to set. (0-4). Lower IDs are evaluated first.
** Segment Length: 0 -> number of LEDs on linear graph. (Ignored if linear style = smooth)
** Threshold Value: Value where this threshold is activated
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxUpdateLinearGraph()===
Update the linear graph with the current sensor value. ShiftX will apply the previously configured thresholds to set bar graph length, color and flash.
* params
** Value: current value representing the linear graph
* returns
** (none)
===sxSetAlert()===
Direct set an alert indicator. For ShiftX3, ID0=Alert LED on right side; ID1=Alert LED on left side.
* params
** Alert ID: ID of alert (0 -> # of alert indicators)
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetAlertThresh()===
Configures an alert threshold. Up to 5 thresholds can be configured per alert indicator. Thresholds are evaluated by ID, from low to high.
* params
** Alert ID: Id of Alert (0 -> # of alert indicators)
** Threshold ID: Id for threshold to set. (0-4). Lower IDs are evaluated first.
** Threshold Value: Value where this threshold is activated
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if configuration message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxUpdateAlert()===
Updates the current value for the specified Alert. ShiftX will apply the previously configured thresholds to set color and flash.
* params
** Alert ID: Id of Alert (0 -> # of alert indicators)
** Value: current value representing the alert
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetDisplay()===
Directly sets the value of the 7 segment display.
* params
** Digit index (must be 0)
** Charater: 0-9. Can set ASCII value by offsetting the value by 48 (e.g. ASCII - 48)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxSetLed()===
Directly set any available LED on ShiftX
* params
** LED Index: 0 -> # of LEDs on device
** Number of LEDs to set: 0 -> # of LEDs on device (0 = set all remaining)
** Red: Red LED value (0-255)
** Green: Green LED value (0-255)
** Blue: Blue LED value (0-255)
** Flash: 0-10Hz (0 = sold on)
* returns
** true if update message was successfully broadcast to ShiftX (does not indicate if ShiftX has received it)

===sxRxButton()===
* params
** (none)
* returns
** nil if no button presses are available; otherwise:
** button_id (ID of button. left button = 0, right button = 1)
** state: (0 = not pressed; 1 = pressed)
<pre>
local id, state = sxRxButton()
if id ~= nil then println('button ' ..id ..' state ' ..state) end
</pre>

==Helper Functions==
===calcGear()===
A convenience function to calculate the current gear of the vehicle. ''Available in firmware 2.15.0''

Variation 1: Use built in GPS speed channel and RPM channel named "RPM"
* params
** Tire Diameter: Tire diameter, in cm.
** Final Drive Ratio: The ratio of the final drive
** Gear 1 Ratio: Ratio of 1st gear
** Gear 2 Ratio: Ratio of 2nd gear (optional)
** Gear 3 Ratio: Ratio of 3rd gear (optional)
** Gear 4 Ratio: Ratio of 4th gear (optional)
** Gear 5 Ratio: Ratio of 5th gear (optional)
** Gear 6 Ratio: Ratio of 6th gear (optional)
* returns
** detected gear (1-6) or nil if no gear was detected
<pre>
local gear = calcGear(62.7, 3.45, 4.23, 2.52, 1.66, 1.22, 1.0, 0.8)
if gear ~= nil then println('gear: ' ..gear) end
</pre>

Variation 2: Specify Speed and RPM channel
* params
** Speed Channel name
** RPM Channel name
** Tire Diameter: Tire diameter, in cm.
** Final Drive Ratio: The ratio of the final drive
** Gear 1 Ratio: Ratio of 1st gear
** Gear 2 Ratio: Ratio of 2nd gear (optional)
** Gear 3 Ratio: Ratio of 3rd gear (optional)
** Gear 4 Ratio: Ratio of 4th gear (optional)
** Gear 5 Ratio: Ratio of 5th gear (optional)
** Gear 6 Ratio: Ratio of 6th gear (optional)
* returns
** detected gear (1-6) or nil if no gear was detected
<pre>
local gear = calcGear('Speed', 'RPM', 62.7, 3.45, 4.23, 2.52, 1.66, 1.22, 1.0, 0.8)
if gear ~= nil then println('gear: ' ..gear) end
</pre>

RaceCapture on Raspberry Pi

2023-12-22T18:40:04Z

Ddimensia: Changed to reference bookworm as the prefered OS at this point.

=Introduction=

We designed the RaceCapture app to run nearly anywhere - even a Raspberry Pi. And now, for about $100 you can create a hardwired, dedicated dash for your RaceCapture system.

[[image:racecapture_raspberry_pi.jpg|1024px]]

==Benefits==
You get all of the benefits of a dedicated dash:
* '''Automatically runs upon power up''' - you can configure the dash to automatically launch the RaceCapture App - just as you'd expect it to work.
* '''Hard-wired data connection to RaceCapture''' - no wireless connections to configure, with the reliability of a direct wire.
* '''Runs on the bare metal''' - The RaceCapture app runs without Android or iOS; there's no other apps competing for resources, or compromising system stability.
* '''Overheating resistance''' - Your typical mobile device requires extra care in very hot weather to prevent damage to it's internal battery, and will shut down if overheated. With proper heat-sinking, the Raspberry Pi should handle the heat.

==Compatibility==
The RaceCapture app running on the Raspberry Pi is compatible with any hardware version of RaceCapture or PodiumConnect.

[[image:racecapture_raspberry_pi_backside.jpg|1024px]]

==Experimental!==
While the results are pretty great, these instructions are ''currently'' for those adventurous race car hackers who know their away around a command line, comfortable working with hardware and want to dig in. '''Think it's cool, but too much to tackle?''' Rope in your nearest computer/electronics geek - you need one on your race team, anyway. :) '''Or, just use the plug and play option''' and use an Android or iOS device via Bluetooth or WiFi.

==Current status and future plans==
Even though this is brand new and officially experimental in nature, we still made it as easy as reasonably possible: we wrapped up the RaceCapture App into as close to a self-running installer, that can run on a bone stock Raspberry Pi image - only a few changes are required to the default image, detailed below.

'''However''', in the near future we will create a dedicated Raspberry Pi image that you can burn to an SD card and simply boot up, and move towards more official support as we iron out the issues.

===Reporting issues and getting support===
Chances are you'll encounter an issue you'll want to report. Before you do that, [https://github.com/autosportlabs/RaceCapture_App/issues?q=is%3Aopen+is%3Aissue+label%3A%22raspberry+pi%22 check the issue log] to see if it's already known.

Otherwise - the best place for support, feedback and sharing success stories is [http://forum.autosportlabs.com on the forums] . Drop us a note there so we can see the progress of your project!

=Hardware Selection=
===Raspberry Pi===
The RaceCapture app is compatible with Raspberry Pi 5, 4 and 3.
We recommend the Raspberry Pi 4 2GB and higher for best performance and support.

===Display===
The RaceCapture app package is designed to recognize the following screens:

* [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display] with capacitive touch screen;
* Displays supporting the AR1100 resistive touch screen controller.

Other displays can work as well, and additional work may be needed to support the screen's touch controller. If unsure, just pick the [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display]
===Enclosure===
A recommended enclosure is the [http://https://www.amazon.com/dp/B01HV97F64 Smart Pi Touch Case]

You can 3D print a sun shade for this enclosure [[file:P001 Raspberry Pi Display Sun Shade.stl.zip|download the .stl file]] (''Courtesy of Michael Lee'')

[[image:SmartPi_touch_case.jpg|400px]] [[image:RaceCapture_Sun_shade_3dprinted_preview.jpg|400px]]

[[image:RaceCapture_RaspberryPi_sun_shade_dashboard.jpg|800px]]

Installed on Dashboard

===Power Supply===
The Raspberry Pi dashboard requires its own power supply. You'll need a high quality 5v power supply with 2 amps minimum capacity; 3 amps is highly recommended, and ideally one with a low drop out voltage, so power is not cut to the Raspberry Pi when you're loading the main battery, such as when cranking the engine.

'''Suggested Power Supplies'''
* [https://www.amazon.com/Jabinco-LM2596-Converter-3-0-40V-1-5-35V/dp/B0817P8BGB/ Buck Converter based on the LM2596]

====Powering RaceCapture====
After you have power to the Raspberry Pi dashboard, you may notice your RaceCapture device will be powered by the USB cable connected to the Pi, just as if you're powering RaceCapture from your laptop. '''You will still want to power your RaceCapture via 12v'''; see the respective installation guides for information on how to power your device.

===Heat sinking===
If you're running in hot weather, we recommend the standard Raspberry Pi heatsink kit to keep your system cool.

For Pi4 users, we recommend active fan cooling in addition to the heat sink.

=Installation=
==Installing Raspberry Pi OS==
We currently recommend Raspberry Pi OS Lite, Debian Version 12 (bookworm) and require a 64bit version for app versions 2.9.0 and newer.

Download from [https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-64-bit the official site] or use the [https://www.raspberrypi.com/software/ Raspberry Pi imager] and choose "Raspberry Pi OS (other)->Raspberry Pi OS Lite (64-bit)" for the operating system, following the instructions for burning to an SD card.

Once you've created your image, boot up your Raspberry Pi and follow the prompts to set your keyboard language and create a username and password.

You should now be able to login as that user and will be greeted with a command prompt like `user@raspberrypi:~ $`

===Wifi Setup===
Unless you are using a network cable you will need to setup Wifi before proceeding. To do this you need to run the command `sudo raspi-config`,
this will bring up a window with several options. To configure Wifi you will want to select `1 System Options` followed by `S1 Wireless LAN`. It will ask you to select your Wifi country and set your network SSID and network password.

===Timezone===
It is advisable to set the system's timezone before proceeding. This is also accomplished by using raspi-config which is run with the command `sudo raspi-config`. If you are also setting up Wifi you can configure your timezone at the same time you are configuring Wifi.

The timezone setting is configured in `5 Localization Options`->`L2 Timezone`. This will allow you to set the timezone by first selecting your region and a major city in your timezone. When done setting the timezone you can back out of raspi-config by hitting escape until you are back at the command prompt.

===Checking your network===
At this point it is good to make sure your Raspberry Pi is connected to your network. Without this none of the remaining steps will be successful.

An easy way to check that you are connected to the network is to use the command `hostname -I`, this will print out the IP address of your
Raspberry Pi, or a blank line if you are not connected.
<pre>
user@raspberrypi:~ $ hostname -I
192.168.1.183 2601:601:d07f:c107:dfb6:823:b21d:6dff
</pre>

===Updating to latest packages===
It is always good form to update the latest packages after a fresh install. Enter this at the command line:
<pre>
sudo apt update
sudo apt dist-upgrade
</pre>

==RaceCapture App Installation==
For those wanting an installation that automatically launches the dashboard upon login, we have developed
an installation script. The installation script allows for the selection of either running against the
framebuffer or X11, and helps in setting up standard Raspberry Pi configuration settings. As a bonus the installation
script also includes optional features such as Wifi auto reconnect, USB drive automounting and GPIO based shutdown
reboot support.

If you want a more custom installation, such as running in a full Desktop environment, manual instructions are also provided.
===Via Installation Script===
From a command prompt simply run
<pre>sudo sh -c "curl -sL bit.ly/3yTbPyZ | bash"</pre>

The installation script will setup the system configuration files so that screen blanking is disabled and GPU memory is set to 256MB.
It will then prompt with a series of questions and configuration options, allowing you to customize the installation.
====Configuration Options====
The installation script prompts for the following:
=====Auto Login=====
* Whether to enable auto login upon startup, if not already enabled (Recommendation: Yes)
** This allows the RPi to login as the current user and launch the RaceCapture App upon startup of your Raspberry Pi. Without this you will need to login every time your Raspberry Pi is powered up.
=====RPi3 Official Display Support=====
* If running an RPi3, whether you are running an Official RPi display.
** Only select yes if you are using a RPi3 with an Official RPi display plugged into the LCD/MIPI connector on the board. Enabling this will disable HDMI support as the RPi3 doesn't appear to automatically detect LCD screens properly.
=====Installation Type=====
* Which type of installation you want, Framebuffer (traditional installation), or X11 which enables the option of VNC support
* If X11 was chosen:
** Whether to enable VNC and if so prompts for entering a VNC password
=====App Features=====
* Watchdog: Enables automatically restarting the RaceCapture App should it crash/exit unexpectedly
* Cursor: Enables a visual mouse pointer (Not recommended for touchscreens)
* Keyboard: Enables an onscreen virtual keyboard for touch screens
=====Extra Features=====
* Wifi Auto Reconnect: Enables a script that detects if your wifi connection is down and attempts to reconnect
* USB Automounting: Enables automatic mounting of USB thumbdrives under /media/usb#, useful for exporting session data or saving configs off the device
* GPIO Reboot/Shutdown: Enables the ability to add a button or switch between GPIO21 and a ground pin, with a short press causing a reboot and a long press causing a graceful shutdown

====Post Configuration Steps====
After you have selected your configuration options the installation script will proceed to download the latest RaceCapture App bundle from
[http://podium.live/software the Podium website], placing it in /opt. If the latest version is already present in /opt it will skip this step.

Next it will unpack the App into /opt/racecapture, prompting you to overwrite and existing installation if one exists.

Finally, the script will modify some files, .bashrc and .xinitrc for X11 installations, so that the Race Capture app launches upon login.

===Manual Installation===
If you choose to install the RaceCapture App manually it's assumed that you have an understanding of the different configuration and installation
options available for the Raspberry Pi. Below is the minimal requirements to run the RaceCapture App via the Framebuffer.
If running in an X11/desktop environment the same instructions should be adequate for running the app in that environment also.

====Install package dependencies====
<pre>
sudo apt install mesa-utils libgles2 libegl1-mesa libegl-mesa0 mtdev-tools
</pre>

====User Permissions====
Ensure that the user is in the dialout, render, video and input groups. It appears these are added by default but to be sure you should run:
<pre>
sudo adduser $USER render
sudo adduser $USER video
sudo adduser $USER input
sudo adduser $USER dialout
</pre>

====Installing the RaceCapture app package====

Download the latest [http://podium.live/software RaceCapture app package for Raspberry Pi] and place it in the /opt/ directory of the Raspberry Pi.

* '''Directly downloading to the Raspberry Pi'''
You can download it directly by getting the URL of the package by right-clicking the download link and copying the URL to your clipboard. Then, use it in the command below:

<pre>
cd /opt
sudo wget <package URL>
</pre>

=====Extract the package=====
Now extract the downloaded package :

<pre>
sudo tar -xjvf <downloaded file>
</pre>

====Launch the app====
Launch the RaceCapture app by running the following command:

<pre>
/opt/racecapture/run_racecapture.sh
</pre>

====Launching with Watchdog====
You can enable an automatic watchdog that re-launches the app in case a crash occurs.

<pre>
/opt/racecapture/run_racecapture.sh -w 1
</pre>

* '''Note:''' You can break out of the application by issuing '''Alt + PrntScn + k''' to the application.

You can further stop all racecapture processes by issuing the following command (e.g. via ssh)
<pre>
killall -9 run_racecapture
</pre>

====Enabling on screen keyboard====
If you don't have a wireless keyboard attached via usb, you can enable an on-screen keyboard.

Edit the kivy config.ini file with:
<pre>
sudo nano ~/.kivy/config.ini
</pre>

and update the keyboard_mode line with:

keyboard_mode = multi

=Connecting to your RaceCapture system=
[[image:racecapture_raspberry_pi_connections.jpg|900px]]
===Powering up===
* Connect your RaceCapture/Pro or RaceCapture/Track to the Raspberry Pi using the USB cable.
* Connect the power to your display and power up.

====Installed via Script====
If you installed via the setup script and enabled autologin, simply let it start upon power-up.
Without autologin you will need to first login as your default user.

====Manual Installation====
See [[#Launch_the_app]]

===Connection and usage===

Once the RaceCapture App is running, it will connect automatically over USB. You can use the app just as you would on Android or iOS.

=Extra Features=

===Hardwire buttons===

The RaceCapture app responds to keyboard commands for certain behaviors. You can use a USB keyboard - or a device that emulates keyboard commands - to control the RaceCapture App.

Currently there are keyboard commands for the following:
* '''Navigating dashboard screens''' - Use the left and right arrow keys to switch between screens
* '''Escaping from screens / menus''' - The Escape key can be used to exit out of screens and options, just like the 'back' button on Android.
* '''Acknowledging alerts''' - Use the following keys to acknowledge alerts, including responding to pit-to-car alerts:
** K : to indicate 'Yes' or 'OK'
** N : to indicate 'No"

=Additional Tips=
See this link for additional tips on how to setup the Pi and speed up the boot times. This should be especially helpful for beginners.

https://wiki.autosportlabs.com/Raspberry_Pi_Tips

Logfiles for troubleshooting can be found at

/home/pi

RaceCapture on Raspberry Pi

2023-11-21T18:11:47Z

Ddimensia: /* Installing Raspberry Pi OS */

=Introduction=

We designed the RaceCapture app to run nearly anywhere - even a Raspberry Pi. And now, for about $100 you can create a hardwired, dedicated dash for your RaceCapture system.

[[image:racecapture_raspberry_pi.jpg|1024px]]

==Benefits==
You get all of the benefits of a dedicated dash:
* '''Automatically runs upon power up''' - you can configure the dash to automatically launch the RaceCapture App - just as you'd expect it to work.
* '''Hard-wired data connection to RaceCapture''' - no wireless connections to configure, with the reliability of a direct wire.
* '''Runs on the bare metal''' - The RaceCapture app runs without Android or iOS; there's no other apps competing for resources, or compromising system stability.
* '''Overheating resistance''' - Your typical mobile device requires extra care in very hot weather to prevent damage to it's internal battery, and will shut down if overheated. With proper heat-sinking, the Raspberry Pi should handle the heat.

==Compatibility==
The RaceCapture app running on the Raspberry Pi is compatible with any hardware version of RaceCapture or PodiumConnect.

[[image:racecapture_raspberry_pi_backside.jpg|1024px]]

==Experimental!==
While the results are pretty great, these instructions are ''currently'' for those adventurous race car hackers who know their away around a command line, comfortable working with hardware and want to dig in. '''Think it's cool, but too much to tackle?''' Rope in your nearest computer/electronics geek - you need one on your race team, anyway. :) '''Or, just use the plug and play option''' and use an Android or iOS device via Bluetooth or WiFi.

==Current status and future plans==
Even though this is brand new and officially experimental in nature, we still made it as easy as reasonably possible: we wrapped up the RaceCapture App into as close to a self-running installer, that can run on a bone stock Raspberry Pi image - only a few changes are required to the default image, detailed below.

'''However''', in the near future we will create a dedicated Raspberry Pi image that you can burn to an SD card and simply boot up, and move towards more official support as we iron out the issues.

===Reporting issues and getting support===
Chances are you'll encounter an issue you'll want to report. Before you do that, [https://github.com/autosportlabs/RaceCapture_App/issues?q=is%3Aopen+is%3Aissue+label%3A%22raspberry+pi%22 check the issue log] to see if it's already known.

Otherwise - the best place for support, feedback and sharing success stories is [http://forum.autosportlabs.com on the forums] . Drop us a note there so we can see the progress of your project!

=Hardware Selection=
===Raspberry Pi===
The RaceCapture app is compatible with Raspberry Pi 4 and 3.
We recommend the Raspberry Pi 4 2GB and higher for best performance and support.

===Display===
The RaceCapture app package is designed to recognize the following screens:

* [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display] with capacitive touch screen;
* Displays supporting the AR1100 resistive touch screen controller.

Other displays can work as well, and additional work may be needed to support the screen's touch controller. If unsure, just pick the [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display]
===Enclosure===
A recommended enclosure is the [http://https://www.amazon.com/dp/B01HV97F64 Smart Pi Touch Case]

You can 3D print a sun shade for this enclosure [[file:P001 Raspberry Pi Display Sun Shade.stl.zip|download the .stl file]] (''Courtesy of Michael Lee'')

[[image:SmartPi_touch_case.jpg|400px]] [[image:RaceCapture_Sun_shade_3dprinted_preview.jpg|400px]]

[[image:RaceCapture_RaspberryPi_sun_shade_dashboard.jpg|800px]]

Installed on Dashboard

===Power Supply===
The Raspberry Pi dashboard requires its own power supply. You'll need a high quality 5v power supply with 2 amps minimum capacity; 3 amps is highly recommended, and ideally one with a low drop out voltage, so power is not cut to the Raspberry Pi when you're loading the main battery, such as when cranking the engine.

'''Suggested Power Supplies'''
* [https://www.amazon.com/Jabinco-LM2596-Converter-3-0-40V-1-5-35V/dp/B0817P8BGB/ Buck Converter based on the LM2596]

====Powering RaceCapture====
After you have power to the Raspberry Pi dashboard, you may notice your RaceCapture device will be powered by the USB cable connected to the Pi, just as if you're powering RaceCapture from your laptop. '''You will still want to power your RaceCapture via 12v'''; see the respective installation guides for information on how to power your device.

===Heat sinking===
If you're running in hot weather, we recommend the standard Raspberry Pi heatsink kit to keep your system cool.

For Pi4 users, we recommend active fan cooling in addition to the heat sink.

=Installation=
==Installing Raspberry Pi OS==
We currently recommend Raspberry Pi OS Lite, Debian Version 11 (bullseye) and require a 64bit version for app versions 2.9.0 and newer.

Download from [https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy-64-bit the official site] or use the [https://www.raspberrypi.com/software/ Raspberry Pi imager] and choose "Raspberry Pi OS (other)->Raspberry Pi OS (Legacy, 64-bit) Lite" for the operating system, following the instructions for burning to an SD card.

Once you've created your image, boot up your Raspberry Pi and follow the prompts to set your keyboard language and create a username and password.

You should now be able to login as that user and will be greeted with a command prompt like `user@raspberrypi:~ $`

===Wifi Setup===
Unless you are using a network cable you will need to setup Wifi before proceeding. To do this you need to run the command `sudo raspi-config`,
this will bring up a window with several options. To configure Wifi you will want to select `1 System Options` followed by `S1 Wireless LAN`. It will ask you to select your Wifi country and set your network SSID and network password.

===Timezone===
It is advisable to set the system's timezone before proceeding. This is also accomplished by using raspi-config which is run with the command `sudo raspi-config`. If you are also setting up Wifi you can configure your timezone at the same time you are configuring Wifi.

The timezone setting is configured in `5 Localization Options`->`L2 Timezone`. This will allow you to set the timezone by first selecting your region and a major city in your timezone. When done setting the timezone you can back out of raspi-config by hitting escape until you are back at the command prompt.

===Checking your network===
At this point it is good to make sure your Raspberry Pi is connected to your network. Without this none of the remaining steps will be successful.

An easy way to check that you are connected to the network is to use the command `hostname -I`, this will print out the IP address of your
Raspberry Pi, or a blank line if you are not connected.
<pre>
user@raspberrypi:~ $ hostname -I
192.168.1.183 2601:601:d07f:c107:dfb6:823:b21d:6dff
</pre>

===Updating to latest packages===
It is always good form to update the latest packages after a fresh install. Enter this at the command line:
<pre>
sudo apt update
sudo apt dist-upgrade
</pre>

==RaceCapture App Installation==
For those wanting an installation that automatically launches the dashboard upon login, we have developed
an installation script. The installation script allows for the selection of either running against the
framebuffer or X11, and helps in setting up standard Raspberry Pi configuration settings. As a bonus the installation
script also includes optional features such as Wifi auto reconnect, USB drive automounting and GPIO based shutdown
reboot support.

If you want a more custom installation, such as running in a full Desktop environment, manual instructions are also provided.
===Via Installation Script===
From a command prompt simply run
<pre>sudo sh -c "curl -sL bit.ly/3yTbPyZ | bash"</pre>

The installation script will setup the system configuration files so that screen blanking is disabled and GPU memory is set to 256MB.
It will then prompt with a series of questions and configuration options, allowing you to customize the installation.
====Configuration Options====
The installation script prompts for the following:
=====Auto Login=====
* Whether to enable auto login upon startup, if not already enabled (Recommendation: Yes)
** This allows the RPi to login as the current user and launch the RaceCapture App upon startup of your Raspberry Pi. Without this you will need to login every time your Raspberry Pi is powered up.
=====RPi3 Official Display Support=====
* If running an RPi3, whether you are running an Official RPi display.
** Only select yes if you are using a RPi3 with an Official RPi display plugged into the LCD/MIPI connector on the board. Enabling this will disable HDMI support as the RPi3 doesn't appear to automatically detect LCD screens properly.
=====Installation Type=====
* Which type of installation you want, Framebuffer (traditional installation), or X11 which enables the option of VNC support
* If X11 was chosen:
** Whether to enable VNC and if so prompts for entering a VNC password
=====App Features=====
* Watchdog: Enables automatically restarting the RaceCapture App should it crash/exit unexpectedly
* Cursor: Enables a visual mouse pointer (Not recommended for touchscreens)
* Keyboard: Enables an onscreen virtual keyboard for touch screens
=====Extra Features=====
* Wifi Auto Reconnect: Enables a script that detects if your wifi connection is down and attempts to reconnect
* USB Automounting: Enables automatic mounting of USB thumbdrives under /media/usb#, useful for exporting session data or saving configs off the device
* GPIO Reboot/Shutdown: Enables the ability to add a button or switch between GPIO21 and a ground pin, with a short press causing a reboot and a long press causing a graceful shutdown

====Post Configuration Steps====
After you have selected your configuration options the installation script will proceed to download the latest RaceCapture App bundle from
[http://podium.live/software the Podium website], placing it in /opt. If the latest version is already present in /opt it will skip this step.

Next it will unpack the App into /opt/racecapture, prompting you to overwrite and existing installation if one exists.

Finally, the script will modify some files, .bashrc and .xinitrc for X11 installations, so that the Race Capture app launches upon login.

===Manual Installation===
If you choose to install the RaceCapture App manually it's assumed that you have an understanding of the different configuration and installation
options available for the Raspberry Pi. Below is the minimal requirements to run the RaceCapture App via the Framebuffer.
If running in an X11/desktop environment the same instructions should be adequate for running the app in that environment also.

====Install package dependencies====
<pre>
sudo apt install mesa-utils libgles2 libegl1-mesa libegl-mesa0 mtdev-tools
</pre>

====User Permissions====
Ensure that the user is in the dialout, render, video and input groups. It appears these are added by default but to be sure you should run:
<pre>
sudo adduser $USER render
sudo adduser $USER video
sudo adduser $USER input
sudo adduser $USER dialout
</pre>

====Installing the RaceCapture app package====

Download the latest [http://podium.live/software RaceCapture app package for Raspberry Pi] and place it in the /opt/ directory of the Raspberry Pi.

* '''Directly downloading to the Raspberry Pi'''
You can download it directly by getting the URL of the package by right-clicking the download link and copying the URL to your clipboard. Then, use it in the command below:

<pre>
cd /opt
sudo wget <package URL>
</pre>

=====Extract the package=====
Now extract the downloaded package :

<pre>
sudo tar -xjvf <downloaded file>
</pre>

====Launch the app====
Launch the RaceCapture app by running the following command:

<pre>
/opt/racecapture/run_racecapture.sh
</pre>

====Launching with Watchdog====
You can enable an automatic watchdog that re-launches the app in case a crash occurs.

<pre>
/opt/racecapture/run_racecapture.sh -w 1
</pre>

* '''Note:''' You can break out of the application by issuing '''Alt + PrntScn + k''' to the application.

You can further stop all racecapture processes by issuing the following command (e.g. via ssh)
<pre>
killall -9 run_racecapture
</pre>

====Enabling on screen keyboard====
If you don't have a wireless keyboard attached via usb, you can enable an on-screen keyboard.

Edit the kivy config.ini file with:
<pre>
sudo nano ~/.kivy/config.ini
</pre>

and update the keyboard_mode line with:

keyboard_mode = multi

=Connecting to your RaceCapture system=
[[image:racecapture_raspberry_pi_connections.jpg|900px]]
===Powering up===
* Connect your RaceCapture/Pro or RaceCapture/Track to the Raspberry Pi using the USB cable.
* Connect the power to your display and power up.

====Installed via Script====
If you installed via the setup script and enabled autologin, simply let it start upon power-up.
Without autologin you will need to first login as your default user.

====Manual Installation====
See [[#Launch_the_app]]

===Connection and usage===

Once the RaceCapture App is running, it will connect automatically over USB. You can use the app just as you would on Android or iOS.

=Extra Features=

===Hardwire buttons===

The RaceCapture app responds to keyboard commands for certain behaviors. You can use a USB keyboard - or a device that emulates keyboard commands - to control the RaceCapture App.

Currently there are keyboard commands for the following:
* '''Navigating dashboard screens''' - Use the left and right arrow keys to switch between screens
* '''Escaping from screens / menus''' - The Escape key can be used to exit out of screens and options, just like the 'back' button on Android.
* '''Acknowledging alerts''' - Use the following keys to acknowledge alerts, including responding to pit-to-car alerts:
** K : to indicate 'Yes' or 'OK'
** N : to indicate 'No"

=Additional Tips=
See this link for additional tips on how to setup the Pi and speed up the boot times. This should be especially helpful for beginners.

https://wiki.autosportlabs.com/Raspberry_Pi_Tips

Logfiles for troubleshooting can be found at

/home/pi

RaceCapture on Raspberry Pi

2023-10-13T17:13:56Z

Ddimensia: Updated links to point to 'Legacy' OS version

=Introduction=

We designed the RaceCapture app to run nearly anywhere - even a Raspberry Pi. And now, for about $100 you can create a hardwired, dedicated dash for your RaceCapture system.

[[image:racecapture_raspberry_pi.jpg|1024px]]

==Benefits==
You get all of the benefits of a dedicated dash:
* '''Automatically runs upon power up''' - you can configure the dash to automatically launch the RaceCapture App - just as you'd expect it to work.
* '''Hard-wired data connection to RaceCapture''' - no wireless connections to configure, with the reliability of a direct wire.
* '''Runs on the bare metal''' - The RaceCapture app runs without Android or iOS; there's no other apps competing for resources, or compromising system stability.
* '''Overheating resistance''' - Your typical mobile device requires extra care in very hot weather to prevent damage to it's internal battery, and will shut down if overheated. With proper heat-sinking, the Raspberry Pi should handle the heat.

==Compatibility==
The RaceCapture app running on the Raspberry Pi is compatible with any hardware version of RaceCapture or PodiumConnect.

[[image:racecapture_raspberry_pi_backside.jpg|1024px]]

==Experimental!==
While the results are pretty great, these instructions are ''currently'' for those adventurous race car hackers who know their away around a command line, comfortable working with hardware and want to dig in. '''Think it's cool, but too much to tackle?''' Rope in your nearest computer/electronics geek - you need one on your race team, anyway. :) '''Or, just use the plug and play option''' and use an Android or iOS device via Bluetooth or WiFi.

==Current status and future plans==
Even though this is brand new and officially experimental in nature, we still made it as easy as reasonably possible: we wrapped up the RaceCapture App into as close to a self-running installer, that can run on a bone stock Raspberry Pi image - only a few changes are required to the default image, detailed below.

'''However''', in the near future we will create a dedicated Raspberry Pi image that you can burn to an SD card and simply boot up, and move towards more official support as we iron out the issues.

===Reporting issues and getting support===
Chances are you'll encounter an issue you'll want to report. Before you do that, [https://github.com/autosportlabs/RaceCapture_App/issues?q=is%3Aopen+is%3Aissue+label%3A%22raspberry+pi%22 check the issue log] to see if it's already known.

Otherwise - the best place for support, feedback and sharing success stories is [http://forum.autosportlabs.com on the forums] . Drop us a note there so we can see the progress of your project!

=Hardware Selection=
===Raspberry Pi===
The RaceCapture app is compatible with Raspberry Pi 4 and 3.
We recommend the Raspberry Pi 4 2GB and higher for best performance and support.

===Display===
The RaceCapture app package is designed to recognize the following screens:

* [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display] with capacitive touch screen;
* Displays supporting the AR1100 resistive touch screen controller.

Other displays can work as well, and additional work may be needed to support the screen's touch controller. If unsure, just pick the [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display]
===Enclosure===
A recommended enclosure is the [http://https://www.amazon.com/dp/B01HV97F64 Smart Pi Touch Case]

You can 3D print a sun shade for this enclosure [[file:P001 Raspberry Pi Display Sun Shade.stl.zip|download the .stl file]] (''Courtesy of Michael Lee'')

[[image:SmartPi_touch_case.jpg|400px]] [[image:RaceCapture_Sun_shade_3dprinted_preview.jpg|400px]]

[[image:RaceCapture_RaspberryPi_sun_shade_dashboard.jpg|800px]]

Installed on Dashboard

===Power Supply===
The Raspberry Pi dashboard requires its own power supply. You'll need a high quality 5v power supply with 2 amps minimum capacity; 3 amps is highly recommended, and ideally one with a low drop out voltage, so power is not cut to the Raspberry Pi when you're loading the main battery, such as when cranking the engine.

'''Suggested Power Supplies'''
* [https://www.amazon.com/Jabinco-LM2596-Converter-3-0-40V-1-5-35V/dp/B0817P8BGB/ Buck Converter based on the LM2596]

====Powering RaceCapture====
After you have power to the Raspberry Pi dashboard, you may notice your RaceCapture device will be powered by the USB cable connected to the Pi, just as if you're powering RaceCapture from your laptop. '''You will still want to power your RaceCapture via 12v'''; see the respective installation guides for information on how to power your device.

===Heat sinking===
If you're running in hot weather, we recommend the standard Raspberry Pi heatsink kit to keep your system cool.

For Pi4 users, we recommend active fan cooling in addition to the heat sink.

=Installation=
==Installing Raspberry Pi OS==
We currently recommend Raspberry Pi OS Lite, Debian Version 11 (bullseye) and require a 64bit version for app versions 2.9.0 and newer.

Download from [https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy-64-bit the official site] or use the [https://www.raspberrypi.com/software/ Raspberry Pi imager] and choose "Raspberry Pi OS (LEGACY, 64-BIT) LITE" for the operating system, following the instructions for burning to an SD card.

Once you've created your image, boot up your Raspberry Pi and follow the prompts to set your keyboard language and create a username and password.

You should now be able to login as that user and will be greeted with a command prompt like `user@raspberrypi:~ $`

===Wifi Setup===
Unless you are using a network cable you will need to setup Wifi before proceeding. To do this you need to run the command `sudo raspi-config`,
this will bring up a window with several options. To configure Wifi you will want to select `1 System Options` followed by `S1 Wireless LAN`. It will ask you to select your Wifi country and set your network SSID and network password.

===Timezone===
It is advisable to set the system's timezone before proceeding. This is also accomplished by using raspi-config which is run with the command `sudo raspi-config`. If you are also setting up Wifi you can configure your timezone at the same time you are configuring Wifi.

The timezone setting is configured in `5 Localization Options`->`L2 Timezone`. This will allow you to set the timezone by first selecting your region and a major city in your timezone. When done setting the timezone you can back out of raspi-config by hitting escape until you are back at the command prompt.

===Checking your network===
At this point it is good to make sure your Raspberry Pi is connected to your network. Without this none of the remaining steps will be successful.

An easy way to check that you are connected to the network is to use the command `hostname -I`, this will print out the IP address of your
Raspberry Pi, or a blank line if you are not connected.
<pre>
user@raspberrypi:~ $ hostname -I
192.168.1.183 2601:601:d07f:c107:dfb6:823:b21d:6dff
</pre>

===Updating to latest packages===
It is always good form to update the latest packages after a fresh install. Enter this at the command line:
<pre>
sudo apt update
sudo apt dist-upgrade
</pre>

==RaceCapture App Installation==
For those wanting an installation that automatically launches the dashboard upon login, we have developed
an installation script. The installation script allows for the selection of either running against the
framebuffer or X11, and helps in setting up standard Raspberry Pi configuration settings. As a bonus the installation
script also includes optional features such as Wifi auto reconnect, USB drive automounting and GPIO based shutdown
reboot support.

If you want a more custom installation, such as running in a full Desktop environment, manual instructions are also provided.
===Via Installation Script===
From a command prompt simply run
<pre>sudo sh -c "curl -sL bit.ly/3yTbPyZ | bash"</pre>

The installation script will setup the system configuration files so that screen blanking is disabled and GPU memory is set to 256MB.
It will then prompt with a series of questions and configuration options, allowing you to customize the installation.
====Configuration Options====
The installation script prompts for the following:
=====Auto Login=====
* Whether to enable auto login upon startup, if not already enabled (Recommendation: Yes)
** This allows the RPi to login as the current user and launch the RaceCapture App upon startup of your Raspberry Pi. Without this you will need to login every time your Raspberry Pi is powered up.
=====RPi3 Official Display Support=====
* If running an RPi3, whether you are running an Official RPi display.
** Only select yes if you are using a RPi3 with an Official RPi display plugged into the LCD/MIPI connector on the board. Enabling this will disable HDMI support as the RPi3 doesn't appear to automatically detect LCD screens properly.
=====Installation Type=====
* Which type of installation you want, Framebuffer (traditional installation), or X11 which enables the option of VNC support
* If X11 was chosen:
** Whether to enable VNC and if so prompts for entering a VNC password
=====App Features=====
* Watchdog: Enables automatically restarting the RaceCapture App should it crash/exit unexpectedly
* Cursor: Enables a visual mouse pointer (Not recommended for touchscreens)
* Keyboard: Enables an onscreen virtual keyboard for touch screens
=====Extra Features=====
* Wifi Auto Reconnect: Enables a script that detects if your wifi connection is down and attempts to reconnect
* USB Automounting: Enables automatic mounting of USB thumbdrives under /media/usb#, useful for exporting session data or saving configs off the device
* GPIO Reboot/Shutdown: Enables the ability to add a button or switch between GPIO21 and a ground pin, with a short press causing a reboot and a long press causing a graceful shutdown

====Post Configuration Steps====
After you have selected your configuration options the installation script will proceed to download the latest RaceCapture App bundle from
[http://podium.live/software the Podium website], placing it in /opt. If the latest version is already present in /opt it will skip this step.

Next it will unpack the App into /opt/racecapture, prompting you to overwrite and existing installation if one exists.

Finally, the script will modify some files, .bashrc and .xinitrc for X11 installations, so that the Race Capture app launches upon login.

===Manual Installation===
If you choose to install the RaceCapture App manually it's assumed that you have an understanding of the different configuration and installation
options available for the Raspberry Pi. Below is the minimal requirements to run the RaceCapture App via the Framebuffer.
If running in an X11/desktop environment the same instructions should be adequate for running the app in that environment also.

====Install package dependencies====
<pre>
sudo apt install mesa-utils libgles2 libegl1-mesa libegl-mesa0 mtdev-tools
</pre>

====User Permissions====
Ensure that the user is in the dialout, render, video and input groups. It appears these are added by default but to be sure you should run:
<pre>
sudo adduser $USER render
sudo adduser $USER video
sudo adduser $USER input
sudo adduser $USER dialout
</pre>

====Installing the RaceCapture app package====

Download the latest [http://podium.live/software RaceCapture app package for Raspberry Pi] and place it in the /opt/ directory of the Raspberry Pi.

* '''Directly downloading to the Raspberry Pi'''
You can download it directly by getting the URL of the package by right-clicking the download link and copying the URL to your clipboard. Then, use it in the command below:

<pre>
cd /opt
sudo wget <package URL>
</pre>

=====Extract the package=====
Now extract the downloaded package :

<pre>
sudo tar -xjvf <downloaded file>
</pre>

====Launch the app====
Launch the RaceCapture app by running the following command:

<pre>
/opt/racecapture/run_racecapture.sh
</pre>

====Launching with Watchdog====
You can enable an automatic watchdog that re-launches the app in case a crash occurs.

<pre>
/opt/racecapture/run_racecapture.sh -w 1
</pre>

* '''Note:''' You can break out of the application by issuing '''Alt + PrntScn + k''' to the application.

You can further stop all racecapture processes by issuing the following command (e.g. via ssh)
<pre>
killall -9 run_racecapture
</pre>

====Enabling on screen keyboard====
If you don't have a wireless keyboard attached via usb, you can enable an on-screen keyboard.

Edit the kivy config.ini file with:
<pre>
sudo nano ~/.kivy/config.ini
</pre>

and update the keyboard_mode line with:

keyboard_mode = multi

=Connecting to your RaceCapture system=
[[image:racecapture_raspberry_pi_connections.jpg|900px]]
===Powering up===
* Connect your RaceCapture/Pro or RaceCapture/Track to the Raspberry Pi using the USB cable.
* Connect the power to your display and power up.

====Installed via Script====
If you installed via the setup script and enabled autologin, simply let it start upon power-up.
Without autologin you will need to first login as your default user.

====Manual Installation====
See [[#Launch_the_app]]

===Connection and usage===

Once the RaceCapture App is running, it will connect automatically over USB. You can use the app just as you would on Android or iOS.

=Extra Features=

===Hardwire buttons===

The RaceCapture app responds to keyboard commands for certain behaviors. You can use a USB keyboard - or a device that emulates keyboard commands - to control the RaceCapture App.

Currently there are keyboard commands for the following:
* '''Navigating dashboard screens''' - Use the left and right arrow keys to switch between screens
* '''Escaping from screens / menus''' - The Escape key can be used to exit out of screens and options, just like the 'back' button on Android.
* '''Acknowledging alerts''' - Use the following keys to acknowledge alerts, including responding to pit-to-car alerts:
** K : to indicate 'Yes' or 'OK'
** N : to indicate 'No"

=Additional Tips=
See this link for additional tips on how to setup the Pi and speed up the boot times. This should be especially helpful for beginners.

https://wiki.autosportlabs.com/Raspberry_Pi_Tips

Logfiles for troubleshooting can be found at

/home/pi

RaceCapture on Raspberry Pi

2023-03-23T04:18:25Z

Ddimensia: Updated instructions for using the rcdash_setup.sh script from https://github.com/autosportlabs/RC-App-RPi-install-script

=Introduction=

We designed the RaceCapture app to run nearly anywhere - even a Raspberry Pi. And now, for about $100 you can create a hardwired, dedicated dash for your RaceCapture system.

[[image:racecapture_raspberry_pi.jpg|1024px]]

==Benefits==
You get all of the benefits of a dedicated dash:
* '''Automatically runs upon power up''' - you can configure the dash to automatically launch the RaceCapture App - just as you'd expect it to work.
* '''Hard-wired data connection to RaceCapture''' - no wireless connections to configure, with the reliability of a direct wire.
* '''Runs on the bare metal''' - The RaceCapture app runs without Android or iOS; there's no other apps competing for resources, or compromising system stability.
* '''Overheating resistance''' - Your typical mobile device requires extra care in very hot weather to prevent damage to it's internal battery, and will shut down if overheated. With proper heat-sinking, the Raspberry Pi should handle the heat.

==Compatibility==
The RaceCapture app running on the Raspberry Pi is compatible with any hardware version of RaceCapture or PodiumConnect.

[[image:racecapture_raspberry_pi_backside.jpg|1024px]]

==Experimental!==
While the results are pretty great, these instructions are ''currently'' for those adventurous race car hackers who know their away around a command line, comfortable working with hardware and want to dig in. '''Think it's cool, but too much to tackle?''' Rope in your nearest computer/electronics geek - you need one on your race team, anyway. :) '''Or, just use the plug and play option''' and use an Android or iOS device via Bluetooth or WiFi.

==Current status and future plans==
Even though this is brand new and officially experimental in nature, we still made it as easy as reasonably possible: we wrapped up the RaceCapture App into as close to a self-running installer, that can run on a bone stock Raspberry Pi image - only a few changes are required to the default image, detailed below.

'''However''', in the near future we will create a dedicated Raspberry Pi image that you can burn to an SD card and simply boot up, and move towards more official support as we iron out the issues.

===Reporting issues and getting support===
Chances are you'll encounter an issue you'll want to report. Before you do that, [https://github.com/autosportlabs/RaceCapture_App/issues?q=is%3Aopen+is%3Aissue+label%3A%22raspberry+pi%22 check the issue log] to see if it's already known.

Otherwise - the best place for support, feedback and sharing success stories is [http://forum.autosportlabs.com on the forums] . Drop us a note there so we can see the progress of your project!

=Hardware Selection=
===Raspberry Pi===
The RaceCapture app is compatible with Raspberry Pi 4 and 3.
We recommend the Raspberry Pi 4 2GB and higher for best performance and support.

===Display===
The RaceCapture app package is designed to recognize the following screens:

* [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display] with capacitive touch screen;
* Displays supporting the AR1100 resistive touch screen controller.

Other displays can work as well, and additional work may be needed to support the screen's touch controller. If unsure, just pick the [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display]
===Enclosure===
A recommended enclosure is the [http://https://www.amazon.com/dp/B01HV97F64 Smart Pi Touch Case]

You can 3D print a sun shade for this enclosure [[file:P001 Raspberry Pi Display Sun Shade.stl.zip|download the .stl file]] (''Courtesy of Michael Lee'')

[[image:SmartPi_touch_case.jpg|400px]] [[image:RaceCapture_Sun_shade_3dprinted_preview.jpg|400px]]

[[image:RaceCapture_RaspberryPi_sun_shade_dashboard.jpg|800px]]

Installed on Dashboard

===Power Supply===
The Raspberry Pi dashboard requires its own power supply. You'll need a high quality 5v power supply with 2 amps minimum capacity; 3 amps is highly recommended, and ideally one with a low drop out voltage, so power is not cut to the Raspberry Pi when you're loading the main battery, such as when cranking the engine.

'''Suggested Power Supplies'''
* [https://www.amazon.com/Jabinco-LM2596-Converter-3-0-40V-1-5-35V/dp/B0817P8BGB/ Buck Converter based on the LM2596]

====Powering RaceCapture====
After you have power to the Raspberry Pi dashboard, you may notice your RaceCapture device will be powered by the USB cable connected to the Pi, just as if you're powering RaceCapture from your laptop. '''You will still want to power your RaceCapture via 12v'''; see the respective installation guides for information on how to power your device.

===Heat sinking===
If you're running in hot weather, we recommend the standard Raspberry Pi heatsink kit to keep your system cool.

For Pi4 users, we recommend active fan cooling in addition to the heat sink.

=Installation=
==Installing Raspberry Pi OS==
We currently recommend Raspberry Pi OS Lite, Debian Version 11 (bullseye) and require a 64bit version for app versions 2.9.0 and newer.

Download from [https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-64-bit the official site] or use the [https://www.raspberrypi.com/software/ Raspberry Pi imager], following the instructions for burning to an SD card.

Once you've created your image, boot up your Raspberry Pi and follow the prompts to set your keyboard language and create a username and password.

You should now be able to login as that user and will be greeted with a command prompt like `user@raspberrypi:~ $`

===Wifi Setup===
Unless you are using a network cable you will need to setup Wifi before proceeding. To do this you need to run the command `sudo raspi-config`,
this will bring up a window with several options. To configure Wifi you will want to select `1 System Options` followed by `S1 Wireless LAN`. It will ask you to select your Wifi country and set your network SSID and network password.

===Timezone===
It is advisable to set the system's timezone before proceeding. This is also accomplished by using raspi-config which is run with the command `sudo raspi-config`. If you are also setting up Wifi you can configure your timezone at the same time you are configuring Wifi.

The timezone setting is configured in `5 Localization Options`->`L2 Timezone`. This will allow you to set the timezone by first selecting your region and a major city in your timezone. When done setting the timezone you can back out of raspi-config by hitting escape until you are back at the command prompt.

===Checking your network===
At this point it is good to make sure your Raspberry Pi is connected to your network. Without this none of the remaining steps will be successful.

An easy way to check that you are connected to the network is to use the command `hostname -I`, this will print out the IP address of your
Raspberry Pi, or a blank line if you are not connected.
<pre>
user@raspberrypi:~ $ hostname -I
192.168.1.183 2601:601:d07f:c107:dfb6:823:b21d:6dff
</pre>

===Updating to latest packages===
It is always good form to update the latest packages after a fresh install. Enter this at the command line:
<pre>
sudo apt update
sudo apt dist-upgrade
</pre>

==RaceCapture App Installation==
For those wanting an installation that automatically launches the dashboard upon login, we have developed
an installation script. The installation script allows for the selection of either running against the
framebuffer or X11, and helps in setting up standard Raspberry Pi configuration settings. As a bonus the installation
script also includes optional features such as Wifi auto reconnect, USB drive automounting and GPIO based shutdown
reboot support.

If you want a more custom installation, such as running in a full Desktop environment, manual instructions are also provided.
===Via Installation Script===
From a command prompt simply run
<pre>sudo sh -c "curl -sL bit.ly/3yTbPyZ | bash"</pre>

The installation script will setup the system configuration files so that screen blanking is disabled and GPU memory is set to 256MB.
It will then prompt with a series of questions and configuration options, allowing you to customize the installation.
====Configuration Options====
The installation script prompts for the following:
=====Auto Login=====
* Whether to enable auto login upon startup, if not already enabled (Recommendation: Yes)
** This allows the RPi to login as the current user and launch the RaceCapture App upon startup of your Raspberry Pi. Without this you will need to login every time your Raspberry Pi is powered up.
=====RPi3 Official Display Support=====
* If running an RPi3, whether you are running an Official RPi display.
** Only select yes if you are using a RPi3 with an Official RPi display plugged into the LCD/MIPI connector on the board. Enabling this will disable HDMI support as the RPi3 doesn't appear to automatically detect LCD screens properly.
=====Installation Type=====
* Which type of installation you want, Framebuffer (traditional installation), or X11 which enables the option of VNC support
* If X11 was chosen:
** Whether to enable VNC and if so prompts for entering a VNC password
=====App Features=====
* Watchdog: Enables automatically restarting the RaceCapture App should it crash/exit unexpectedly
* Cursor: Enables a visual mouse pointer (Not recommended for touchscreens)
* Keyboard: Enables an onscreen virtual keyboard for touch screens
=====Extra Features=====
* Wifi Auto Reconnect: Enables a script that detects if your wifi connection is down and attempts to reconnect
* USB Automounting: Enables automatic mounting of USB thumbdrives under /media/usb#, useful for exporting session data or saving configs off the device
* GPIO Reboot/Shutdown: Enables the ability to add a button or switch between GPIO21 and a ground pin, with a short press causing a reboot and a long press causing a graceful shutdown

====Post Configuration Steps====
After you have selected your configuration options the installation script will proceed to download the latest RaceCapture App bundle from
[http://podium.live/software the Podium website], placing it in /opt. If the latest version is already present in /opt it will skip this step.

Next it will unpack the App into /opt/racecapture, prompting you to overwrite and existing installation if one exists.

Finally, the script will modify some files, .bashrc and .xinitrc for X11 installations, so that the Race Capture app launches upon login.

===Manual Installation===
If you choose to install the RaceCapture App manually it's assumed that you have an understanding of the different configuration and installation
options available for the Raspberry Pi. Below is the minimal requirements to run the RaceCapture App via the Framebuffer.
If running in an X11/desktop environment the same instructions should be adequate for running the app in that environment also.

====Install package dependencies====
<pre>
sudo apt install mesa-utils libgles2 libegl1-mesa libegl-mesa0 mtdev-tools
</pre>

====User Permissions====
Ensure that the user is in the dialout, render, video and input groups. It appears these are added by default but to be sure you should run:
<pre>
sudo adduser $USER render
sudo adduser $USER video
sudo adduser $USER input
sudo adduser $USER dialout
</pre>

====Installing the RaceCapture app package====

Download the latest [http://podium.live/software RaceCapture app package for Raspberry Pi] and place it in the /opt/ directory of the Raspberry Pi.

* '''Directly downloading to the Raspberry Pi'''
You can download it directly by getting the URL of the package by right-clicking the download link and copying the URL to your clipboard. Then, use it in the command below:

<pre>
cd /opt
sudo wget <package URL>
</pre>

=====Extract the package=====
Now extract the downloaded package :

<pre>
sudo tar -xjvf <downloaded file>
</pre>

====Launch the app====
Launch the RaceCapture app by running the following command:

<pre>
/opt/racecapture/run_racecapture.sh
</pre>

====Launching with Watchdog====
You can enable an automatic watchdog that re-launches the app in case a crash occurs.

<pre>
/opt/racecapture/run_racecapture.sh -w 1
</pre>

* '''Note:''' You can break out of the application by issuing '''Alt + PrntScn + k''' to the application.

You can further stop all racecapture processes by issuing the following command (e.g. via ssh)
<pre>
killall -9 run_racecapture
</pre>

====Enabling on screen keyboard====
If you don't have a wireless keyboard attached via usb, you can enable an on-screen keyboard.

Edit the kivy config.ini file with:
<pre>
sudo nano ~/.kivy/config.ini
</pre>

and update the keyboard_mode line with:

keyboard_mode = multi

=Connecting to your RaceCapture system=
[[image:racecapture_raspberry_pi_connections.jpg|900px]]
===Powering up===
* Connect your RaceCapture/Pro or RaceCapture/Track to the Raspberry Pi using the USB cable.
* Connect the power to your display and power up.

====Installed via Script====
If you installed via the setup script and enabled autologin, simply let it start upon power-up.
Without autologin you will need to first login as your default user.

====Manual Installation====
See [[#Launch_the_app]]

===Connection and usage===

Once the RaceCapture App is running, it will connect automatically over USB. You can use the app just as you would on Android or iOS.

=Extra Features=

===Hardwire buttons===

The RaceCapture app responds to keyboard commands for certain behaviors. You can use a USB keyboard - or a device that emulates keyboard commands - to control the RaceCapture App.

Currently there are keyboard commands for the following:
* '''Navigating dashboard screens''' - Use the left and right arrow keys to switch between screens
* '''Escaping from screens / menus''' - The Escape key can be used to exit out of screens and options, just like the 'back' button on Android.
* '''Acknowledging alerts''' - Use the following keys to acknowledge alerts, including responding to pit-to-car alerts:
** K : to indicate 'Yes' or 'OK'
** N : to indicate 'No"

=Additional Tips=
See this link for additional tips on how to setup the Pi and speed up the boot times. This should be especially helpful for beginners.

https://wiki.autosportlabs.com/Raspberry_Pi_Tips

Logfiles for troubleshooting can be found at

/home/pi

RaceCapture on Raspberry Pi

2023-03-21T05:06:02Z

Ddimensia: /* Installing Rasbian OS */

=Introduction=

We designed the RaceCapture app to run nearly anywhere - even a Raspberry Pi. And now, for about $100 you can create a hardwired, dedicated dash for your RaceCapture system.

[[image:racecapture_raspberry_pi.jpg|1024px]]

==Benefits==
You get all of the benefits of a dedicated dash:
* '''Automatically runs upon power up''' - you can configure the dash to automatically launch the RaceCapture App - just as you'd expect it to work.
* '''Hard-wired data connection to RaceCapture''' - no wireless connections to configure, with the reliability of a direct wire.
* '''Runs on the bare metal''' - The RaceCapture app runs without Android or iOS; there's no other apps competing for resources, or compromising system stability.
* '''Overheating resistance''' - Your typical mobile device requires extra care in very hot weather to prevent damage to it's internal battery, and will shut down if overheated. With proper heat-sinking, the Raspberry Pi should handle the heat.

==Compatibility==
The RaceCapture app running on the Raspberry Pi is compatible with any hardware version of RaceCapture or PodiumConnect.

[[image:racecapture_raspberry_pi_backside.jpg|1024px]]

==Experimental!==
While the results are pretty great, these instructions are ''currently'' for those adventurous race car hackers who know their away around a command line, comfortable working with hardware and want to dig in. '''Think it's cool, but too much to tackle?''' Rope in your nearest computer/electronics geek - you need one on your race team, anyway. :) '''Or, just use the plug and play option''' and use an Android or iOS device via Bluetooth or WiFi.

==Current status and future plans==
Even though this is brand new and officially experimental in nature, we still made it as easy as reasonably possible: we wrapped up the RaceCapture App into as close to a self-running installer, that can run on a bone stock Raspberry Pi image - only a few changes are required to the default image, detailed below.

'''However''', in the near future we will create a dedicated Raspberry Pi image that you can burn to an SD card and simply boot up, and move towards more official support as we iron out the issues.

===Reporting issues and getting support===
Chances are you'll encounter an issue you'll want to report. Before you do that, [https://github.com/autosportlabs/RaceCapture_App/issues?q=is%3Aopen+is%3Aissue+label%3A%22raspberry+pi%22 check the issue log] to see if it's already known.

Otherwise - the best place for support, feedback and sharing success stories is [http://forum.autosportlabs.com on the forums] . Drop us a note there so we can see the progress of your project!

=Hardware Selection=
===Raspberry Pi===
We recommend the Raspberry Pi 4 2GB and higher for best performance and support.

===Display===
The RaceCapture app package is designed to recognize the following screens:

* [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display] with capacitive touch screen;
* Displays supporting the AR1100 resistive touch screen controller.

Other displays can work as well, and additional work may be needed to support the screen's touch controller. If unsure, just pick the [https://www.raspberrypi.org/products/raspberry-pi-touch-display/ Official Raspberry Pi display]
===Enclosure===
A recommended enclosure is the [http://https://www.amazon.com/dp/B01HV97F64 Smart Pi Touch Case]

You can 3D print a sun shade for this enclosure [[file:P001 Raspberry Pi Display Sun Shade.stl.zip|download the .stl file]] (''Courtesy of Michael Lee'')

[[image:SmartPi_touch_case.jpg|400px]] [[image:RaceCapture_Sun_shade_3dprinted_preview.jpg|400px]]

[[image:RaceCapture_RaspberryPi_sun_shade_dashboard.jpg|800px]]

Installed on Dashboard

===Power Supply===
The Raspberry Pi dashboard requires its own power supply. You'll need a high quality 5v power supply with 2 amps minimum capacity; 3 amps is highly recommended, and ideally one with a low drop out voltage, so power is not cut to the Raspberry Pi when you're loading the main battery, such as when cranking the engine.

'''Suggested Power Supplies'''
* [https://www.amazon.com/Jabinco-LM2596-Converter-3-0-40V-1-5-35V/dp/B0817P8BGB/ Buck Converter based on the LM2596]

====Powering RaceCapture====
After you have power to the Raspberry Pi dashboard, you may notice your RaceCapture device will be powered by the USB cable connected to the Pi, just as if you're powering RaceCapture from your laptop. '''You will still want to power your RaceCapture via 12v'''; see the respective installation guides for information on how to power your device.

===Heat sinking===
If you're running in hot weather, we recommend the standard Raspberry Pi heatsink kit to keep your system cool.

For Pi4 users, we recommend active fan cooling in addition to the heat sink.

=Installation=
==Installing Rasbian OS==
We currently recommend Raspberry Pi OS Lite, Debian Version 11 (bullseye) and require a 64bit version for app versions 2.9.0 and newer.

Download from [https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-64-bit the official site] or use the [https://www.raspberrypi.com/software/ Raspberry Pi imager], following the instructions for burning to an SD card.

Once you've created your image, boot up your Raspberry Pi and follow the prompts to set your keyboard language and create a username and password.

You should now be able to login as that user and will be greeted with a command prompt like `user@raspberrypi:~ $`

===Wifi Setup===
Unless you are using a network cable you will need to setup Wifi before proceeding. To do this you need to run the command `sudo raspi-config`,
this will bring up a window with several options. To configure Wifi you will want to select `1 System Options` followed by `S1 Wireless LAN`. It will ask you to select your Wifi country and set your network SSID and network password.

===Timezone===
It is advisable to set the system's timezone before proceeding. This is also accomplished by using raspi-config which is run with the command `sudo raspi-config`. If you are also setting up Wifi you can configure your timezone at the same time you are configuring Wifi.

The timezone setting is configured in `5 Localization Options`->`L2 Timezone`. This will allow you to set the timezone by first selecting your region and a major city in your timezone. When done setting the timezone you can back out of raspi-config by hitting escape until you are back at the command prompt.

===Checking your network===
At this point it is good to make sure your Raspberry Pi is connected to your network. Without this none of the remaining steps will be successful.

An easy way to check that you are connected to the network is to use the command `hostname -I`, this will print out the IP address of your
Raspberry Pi, or a blank line if you are not connected.
<pre>
user@raspberrypi:~ $ hostname -I
192.168.1.183 2601:601:d07f:c107:dfb6:823:b21d:6dff
</pre>

===Updating to latest packages===
It is always good form to update the latest packages after a fresh install. Enter this at the command line:
<pre>
sudo apt update
sudo apt dist-upgrade
</pre>

==Raspberry Pi support==
The RaceCapture app is compatible with Raspberry Pi 4 and 3.

===Enable GPU driver===
Enable Fake KMS under advanced boot options:

<pre>
sudo raspi-config
</pre>

Go to Advanced Options -> GL Driver -> Select OpenGL desktop driver with fake KMS

* Be sure to reboot after exiting raspi-config

==Installing dependencies==
===Activate ssh===
Ssh is used to store passwords used by the app. Steps to ensure it is running:

<pre>
sudo raspi-config
</pre>
Go under Interfacing Options or Advanced Options and start the ssh service.

Next, at the command prompt enter
<pre>
ssh-add
</pre>
to create at least one key.

===Install package dependencies===
<pre>
sudo apt-get install mesa-utils libgles2 libegl1-mesa libegl-mesa0
</pre>
===Change the default password===
For maximum security, change the password for the default user 'pi'

<pre>
> passwd
</pre>

and specify a new, secure password.

===Configure Raspberry Pi base settings===
====Enable Hardware rendering====
Enter the following line to enable hardware accelerated rendering.
<pre>
> sudo adduser pi render
</pre>
* '''Notes''':
** Without this setting, UI rendering will be extremely slow.
** Assumes RaceCapture is launched as pi. If not, replace pi with the user you are logging in as.
** If you're coming in to fix this after the fact, you'll need to reboot/re-login to take effect.

====Enable WiFi====
If you want network capability in addition to the ethernet connection, [https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md enable and configure WiFi per the official documentation]

====(Optional) Enable SSH====
You can optionally enable SSH for remote management from the comfort of your main computer's keyboard and screen.

[https://www.raspberrypi.org/documentation/remote-access/ssh/ Enable and configure ssh per the official documentation]

====Install multi-touch tools====
Install the packages that enable multi-touch interfaces. Enter the following at the command line:

<pre>
> sudo apt-get install mtdev-tools
</pre>

====Configure memory split====
You'll need to bump up the memory made available to the GPU. Increase the default value of 64 to '''256'''.

* '''Via raspi-config tool'''
You can adjust the memory split by running the raspi-config tool. See the [https://www.raspberrypi.org/documentation/configuration/raspi-config.md official documentation]

* '''Editing /boot/config.txt'''

You can adjust the value directly by editing the /boot/config.txt file.

<pre>
> sudo nano /boot/config.txt
</pre>

Find the line containing gpu_mem=64 and change the number to 256

<pre>
gpu_mem=256
</pre>

''Save the file by pressing '''ctrl-x''' then press '''Y''' to confirm.''

==Installing the RaceCapture app package==

Download the latest [http://podium.live/software RaceCapture app package for Raspberry Pi] and place it in the /opt/ directory of the Raspberry Pi.

* '''Directly downloading to the Raspberry Pi'''
You can download it directly by getting the URL of the package by right-clicking the download link and copying the URL to your clipboard. Then, use it in the command below:

<pre>
cd /opt
sudo wget <package URL>
</pre>

===Extract the package===
Now extract the downloaded package :

<pre>
sudo tar -xjvf <downloaded file>
</pre>

===Launch the app===
Launch the RaceCapture app by running the following command:

<pre>
/opt/racecapture/run_racecapture.sh
</pre>

===Launching with Watchdog===
You can enable an automatic watchdog that re-launches the app in case a crash occurs.

<pre>
/opt/racecapture/run_racecapture.sh -w 1
</pre>

* '''Note:''' You can break out of the application by issuing '''Alt + PrntScn + k''' to the application.

You can further stop all racecapture processes by issuing the following command (e.g. via ssh)
<pre>
killall -9 run_racecapture
</pre>

===Enabling on screen keyboard===
If you don't have a wireless keyboard attached via usb, you can enable an on-screen keyboard.

Edit the kivy config.ini file with:
<pre>
sudo nano ~/.kivy/config.ini
</pre>

and update the keyboard_mode line with:

keyboard_mode = multi

==Automatic start upon power up==
To get the full dedicated dashboard experience, you can enable automatic launch of the RaceCapture app upon power up.

To do this, edit the system's startup file:

<pre>
sudo nano /etc/rc.local
</pre>

and add the following line '''before the exit 0''' line.

<pre>
/opt/racecapture/boot_racecapture.sh pi

exit 0
</pre>

''Save the file by pressing '''ctrl-x''' then press '''Y''' to confirm.''

=Connecting to your RaceCapture system=
[[image:racecapture_raspberry_pi_connections.jpg|900px]]
===Powering up===
* Connect the power to your display and power up.
* Connect your RaceCapture/Pro or RaceCapture/Track to the Raspberry Pi using the USB cable.

* Launch the RaceCapture app by running:

<pre>
/opt/racecapture/run_racecapture.sh
</pre>

If you have it set to launch automatically, simply let it start upon power-up.

===Connection and usage===

Once the RaceCapture App is running, it will connect automatically over USB. You can use the app just as you would on Android or iOS.

=Extra Features=

===Hardwire buttons===

The RaceCapture app responds to keyboard commands for certain behaviors. You can use a USB keyboard - or a device that emulates keyboard commands - to control the RaceCapture App.

Currently there are keyboard commands for the following:
* '''Navigating dashboard screens''' - Use the left and right arrow keys to switch between screens
* '''Escaping from screens / menus''' - The Escape key can be used to exit out of screens and options, just like the 'back' button on Android.
* '''Acknowledging alerts''' - Use the following keys to acknowledge alerts, including responding to pit-to-car alerts:
** K : to indicate 'Yes' or 'OK'
** N : to indicate 'No"

=Additional Tips=
See this link for additional tips on how to setup the Pi and speed up the boot times. This should be especially helpful for beginners.

https://wiki.autosportlabs.com/Raspberry_Pi_Tips

Logfiles for troubleshooting can be found at

/home/pi