vbox

get sample

Gets the most recent/current sample data.

vbox.get_sample()

Returns a named tuple of GNSS data. For information on this named tuple see VBOX sample data.

get sample hp

Gets the current sample buffer data.

vbox.get_sample_hp()

Returns a named tuple of GNSS data. For information on this named tuple see VBOX sample data.

init

Initialises the GNSS

vbox.init(mode)

Input Parameters:

mode [int] = What mode to run GNSS in. Any of the following is valid: vbox.VBOX_SRC_GNSS_BASIC, vbox.VBOX_SRC_CAN_VBOX or vbox.VBOX_SRC_NONE.

reset

Resets a stored VBOX value back to zero. The value to reset is selected by the name string.

vbox.reset(name)

Input Parameters:

name[str] = The name of the value to reset. Currently the supported value is “LatAccSmoothMax”, which resets the maximum smoothed lateral acceleration.

rlcrc

Calculates the Racelogic Cyclic Redundancy Check (CRC) over the first len bytes of a buffer and writes the resulting two-byte CRC into the two bytes immediately following the data.

vbox.rlcrc(buf, len)

Input Parameters:

buf[bytearray] = Buffer holding the data that will be checked. It must be at least len + 2 bytes long, as the two CRC bytes are written after the data.
len[int] = The number of bytes over which to calculate the CRC.

set new data callback

Sets the new callback for when you receive new GNSS data on the VBOX Touch

vbox.set_new_data_callback(callback)

Input Parameters:

callback [func] = The callback function to be triggered

sources

Get the data channels supported by the current firmware.

vbox.sources()

Returns a list of the available channels.

Performance Testing

This class is used when performance testing is needed.

Configuration object

This object is used to create a new performance test configuration.

vbox.perftest_cfg(test_type, options, param0, param1, param2, param3)

Input Parameters:

test_type[int] = The type of test, the types and their input are listed below
- vbox.PERFTEST_ACCEL_SPD_SPD Acceleration from speed to speed.
  Options : ROLLOUT_REQ, SLOPE_FALCO_REQ.
  
  Param 0 : Start speed in ms-1.
  
  Param 1 : End speed in ms-1. Must be higher than the start speed.
- vbox.PERFTEST_ACCEL_SPD_DIST Acceleration from speed to distance.
  Options : ROLLOUT_REQ, SLOPE_FALCO_REQ.
  
  Param 0 : Start speed in ms-1.
  
  Param 1 : End distance in m.
- vbox.PERFTEST_ACCEL_DECEL Acceleration from speed to speed then deceleration to speed.
  Options : ROLLOUT_REQ, SLOPE_FALCO_REQ.
  
  Param 0 : Start speed in ms-1.
  
  Param 1 : Mid-test target speed in ms-1. Must be higher than the start speed.
  
  Param 2 : End speed in ms-1. Must be lower than the mid-test target speed.
- vbox.PERFTEST_DECEL_SPD_SPD Deceleration from speed to speed.
  Options : MFDD_PERCENTAGE, MFDD_ABS_SPEED.
  
  Param 0 : Start speed in ms-1.
  
  Param 1 : End speed in ms-1. Must be lower than the start speed.
  
  Param 2 : MFDD start condition. Meaning depends on MFDD option, see MFDD Options below.
  
  Param 3 : MFDD end condition. Meaning depends on MFDD option, see MFDD Options below.
- vbox.PERFTEST_DECEL_TRG_SPD Deceleration from trigger to speed.
  Options : MFDD_PERCENTAGE, MFDD_ABS_SPEED.
  
  Param 0 : Minimum trigger speed in ms-1. Events below this speed are ignored.
  
  Param 1 : End speed in ms-1. Must be lower than the start speed.
  
  Param 2 : MFDD start condition. Meaning depends on MFDD option, see MFDD Options below.
  
  Param 3 : MFDD end condition. Meaning depends on MFDD option, see MFDD Options below.
- vbox.PERFTEST_ACCEL_SPD_END Acceleration from speed to end of acceleration.
  Options : None.
  
  Param 0 : Start speed in ms-1.
  
  Param 1 : Minimum end speed in ms-1. Must be greater than the start speed.

If it only needs 2 parameters then only pass it those and not any extra.

Configuring

Configure the different performance tests.

vbox.perftest_configure(index, config)

Input Parameters:

index[int] = Index of the test to configure. This value must be below VBOX_MAX_PERFTESTS.
config[configuration_object] = The configuration object for the new test. See Configuration object for more details.

Getting data

Get the configuration data from the performance test.

vbox.perftest_get_data(index)

Input Parameters:

index[int] = Index of the test to get the data from.

This returns a named tuple. The type of test performed will change what data this is.

Get Results

Get the most recent performance test results.

vbox.perftest_get_results(index)

Input Parameters:

index[int] = Index of the test to get the results from.

This returns a named tuple. The type of test performed will change what data this is.

Reset

Reset the performance test data.

vbox.perftest_reset(index, reset_type)

Input Parameters:

index[int] = Index to the test to reset.
reset_type[int] = The type of reset to be performed on the performance test:
- vbox.PERFTEST_RST_GBL_ACCEL_ALL = Reset all global acceleration test data.
- vbox.PERFTEST_RST_GBL_ACCEL_SESS = Reset the current session’s global acceleration data.
- vbox.PERFTEST_RST_GBL_ACCEL_LAST = Reset the most recent global acceleration result.
- vbox.PERFTEST_RST_HISTORY = Reset the stored test history.
- vbox.PERFTEST_RST_USER_ACTIVE = Reset the currently active user test.
- vbox.PERFTEST_RST_USER_ALL = Reset all user tests.

Globals

Get

Get the current global performance test values

vbox.perftest_get_global()

This returns a named tuple. The tuple contains the following:

status[int] = Current status of the performance test
accel_last_speed_max_mps[float] = The max speed achieved in the previous session.
accel_last_lngacc_max_mps2[float] = The max acceleration achieved in the previous session.
accel_sess_speed_max_mps[float] = The max speed achieved in the current session.
accel_sess_lngacc_max_mps2[float] = The max acceleration achieved in the current session.

Set

Set data to the current global performance test values.

vbox.perftest_set_global(data)

Input Parameters:

data[dict] = dictionary of the fields to set. You can only set accel_sess_speed_max_mps and accel_sess_lngacc_max_mps2. The keys must be set in the dictionary with an item that is a valid float.

Predictive Lap Timing (plt)

Configuration

Set the predictive lap timing configuration.

vbox.plt_configure(options, rec_min_ms)

Input Parameters:

options[int] = Sets PLT options, see plt_options_t.
rec_min_ms[int] = Sets the minimum valid recorded reference lap period in milliseconds.

Enabled

Sets the predictive lap timing to the state you input.

vbox.plt_enabled(state)

Input Parameters:

state[int] = a number from 0-3 inclusive that mean the following. If not passed a value it defaults to 0.
- 0 = Disables PLT and cancels any current prediction and recording.
- 1 = Enables PLT.
- 2 = Disables any current reference lap
- 3 = Disables any current recording

erase reflap

Erase the predictive lap timing reference laps.

vbox.plt_erase_reflap(region, force, mode)

Input Parameters:

region[int] = Specifies the region(s) to erase:
- VBOX_PLT_RGN_REF to erase the current reference lap region.
- VBOX_PLT_RGN_ALL to erase all reference lap regions.
- Region identifier (0 or 1).
force[bool] = Forces the erasing even if the region is currently active when set to True. Otherwise, this would throw an exception.
mode[int] = Species the erase mode used from the following modes:
- VBOX_PLT_RGN_ERASE_ALL_NOW = immediately erase all specified regions
- VBOX_PLT_RGN_ERASE_1ST_NOW = immediately erase the first SPIFI block in the first region and schedule the rest. This is because the erase takes a while and will block the uPy task until completed which will prevent GUI updates. Even erasing a single block causes noticeable GUI glitches so at some point we should implement an asynchronous SPIFI erase.

get_info

Read in the specified reference lap information.

vbox.plt_get_info(region)

Input Parameters:

region[int] = Specifies the reference lap to read. Either 0 or 1.

It returns a dictionary containing the stored reference lap information if it exists; otherwise it returns None or raises an exception.

get_status

Get the current status of predictive lap timing.

vbox.plt_get_status()

This returns a named tuple with the following fields:

ref_region[int] = Current active reference lap region.
ref_id[int] = Current active reference lap identifier
ref_pt_cnt[int] = Current active refer lap point count
ref_period_ms[float] = Current active reference lap in milliseconds
ref_dist_m[int] = Current active reference lap distance in metres

load_prepare

Start a reference lap load from a uPy application to SPIFI.

vbox.plt_load_prepare()

Loading a reference lap (writing to SPIFI) has 3 stages of functions that must be completed in order:

Start the load using vbox.plt_load_prepare().
Write the reference lap points using repeated calls to vbox.plt_load_point_str().
End the load by writing the reference lap information using vbox.plt_load_info().

load_point_str

Saves a reference lap point to SPIFI.

vbox.plt_load_point_str(buf)

Input Parameters:

buf[string] = Contains a reference lap point as the text stored in a PLT .REF file.

load_info

Save reference lap information to SPIFI and end the reference lap load. This should only be called after vbox.plt_load_prepare() and all its points have been loaded using vbox.plt_load_point_str().

vbox.plt_load_info(buf)

Input Parameters:

buf[bytearray] = This buffer represents the reference lap’s info.

Reference lap structure:

S_Gate_Lng[Int32] = Start gate point longitude in minutes * 10⁵
S_Gate_lat[Int32] = Start gate point latitude in minutes * 10⁵
S_Prev_lng[Int32] = Start previous point longitude in minutes * 10⁵
S_Prev_lat[Int32] = Start previous point latitude in minutes * 10⁵
F_Gate_lng[Int32] = Finish gate point longitude in minutes * 10⁵
F_Gate_lat[Int32] = Finish gate point latitude in minutes * 10⁵
F_Prev_lng[Int32] = Finish previous point longitude in minutes * 10⁵
F_Prev_lat[Int32] = Finish previous point latitude in minutes * 10⁵
BP_Lng[Int32] = Base point longitude in minutes * 10⁵
BP_Lat[Int32] = Base point latitude in minutes * 10⁵
BP_Ratio[Float32] = Base point longitude ratio
Ref_Period[UInt32] = Reference lap period in milliseconds
Lap_Dist[Float32] = Reference lap distance in metres
Flags[UInt32] = Reference lap flags, see PLTINFO_FLG
Num_Points[UInt32] = The number of reference lap points

Note

For a circuit the Start = Finish. In this case, the Finish would be blank
Num_Points should match the number of calls to vbox.plt_load_point_str().

Warning

There is currently limited validation on the information block so make sure that the information that you pass to it is correct.

read_point

Read a reference lap point from SPIFI.

vbox.plt_read_point(index, buf)

Input Parameters:

index[int] = The index of the point to read
buf[bytearray] = Buffer to store the point data

Note

buf has to be large enough to hold a plt_point_t The returned points are that of the current reference lap.

save_prepare

Start a reference lap save from SPIFI to the uPy application.

vbox.plt_save_prepare()

Similarly to loading from uPy to SPIFI, saving a reference lap is a 3-stage process:

Start the save using vbox.plt_save_prepare().
Read the reference lap information using vbox.plt_get_info().
Read the reference lap points using repeated calls to vbox.plt_read_point().

Note

This function disables any current reference lap. However, it is recommended that you do this yourself beforehand.

Gates

Gate configuration

configure

Configure global gate settings

vbox.gates_configure(gate_width)

Input Parameters:

gate_width[int] = used to set the default gate_width in millimetres.

This will set the width of any current or future gates configured using the default gate width.

get

Get the current configuration of a gate

vbox.get_gate_config(index)

Input Parameters:

index[int] = The index of the required gate in the range 0 to VBOX_MAX_GATES

This returns a dictionary if the requested gate is a valid gate configuration, None if it is an invalid gate configuration and will throw an exception if the request is invalid.

The dictionary is formatted in the following way:

Type[int] = The gate type
Id[int] = The gate id
Flags[Bit flags] = Gate status flags
Width_mm[int] = Current gate width in millimetres
IgnoreCount[int] = Current ignore count value
PosLat_minE5[int] = Latitude of gate location in minutes * 10⁵
PosLng_minE5[Int32] = Longitude of gate location in minutes * 10⁵
PrevLat_minE5[Int32] = Latitude of gate previous point in minutes * 10⁵
PrevLng_minE5[Int32] = Longitude of gate previous point in minutes * 10⁵

set

Set a gate’s configuration

vbox.set_gate_config(index, config)

Input Parameters:

index[int] = The index of the required gate in the range 0 to VBOX_MAX_GATES
config[dict] = a dictionary containing the following:
- Type[int] = One of the standard gate types. If you want a standard start gate this should be requested using vbox.gate_request(GATE_TYPE_STANDING_START)
- Id[int] = Used to identify split gates
- Flags[Bit flags] = Gate status flags
- Width_mm[int] = Current gate width in millimetres
- IgnoreCount[int] = Current ignore count value
- PosLat_minE5[int] = Latitude of gate location in minutes * 10⁵
- PosLng_minE5[Int32] = Longitude of gate location in minutes * 10⁵
- PrevLat_minE5[Int32] = Latitude of gate previous point in minutes * 10⁵
- PrevLng_minE5[Int32] = Longitude of gate previous point in minutes * 10⁵

Gate request

Control the gate handling

vbox.gate_request(req_type, *args)

Input Parameters:

req_type[int] = Specifies the type of request. Some of these requests require additional parameters.
- vbox.GATE_REQ_MANUAL_CANCEL (2) = Cancels any pending request from GATE_REQ_MANUAL_REQUEST. Raises an exception if no request is pending
- vbox.GATE_REQ_MANUAL_CONFIRM (4) = Confirms any pending request from GATE_REQ_MANUAL_REQUEST. Raises an exception if no request is pending
- vbox.GATE_REQ_MANUAL_REQUEST (1) = Creates a new request based on the other args specified:
  vbox.GATE_TYPE_START_FINISH (1) = Requests a start/finish gate at the location of the next valid sample.
  
  vbox.GATE_TYPE_FINISH (3) = Requests a finish gate at the location of the next valid sample.
  
  vbox.GATE_TYPE_STANDING_START (7) = Requests a standing start gate at the location of the next valid sample. Then start lap timing from this point.
args = The extra parameters required when using GATE_REQ_MANUAL_REQUEST.

Gate valid - deprecated

Checks if the current gate configuration is valid.

vbox.get_gates_valid()

This returns a boolean of whether it is valid or not. To have a valid gate you need to set your gate to be either a start/finish, start or finish gate. This function is deprecated as it does not account for the newer gate types.

laps

This function is used for all lap timing functionality including getting and setting.

vbox.laps(req_type, *args)

Input Parameters:

req_type(int) = The type of request. This can be the following:
- vbox.GATE_REQ_MANUAL_CANCEL (2) = Cancels any pending request from GATE_REQ_MANUAL_REQUEST. Raises an exception if no request is pending
- vbox.GATE_REQ_MANUAL_CONFIRM (4) = Confirms any pending request from GATE_REQ_MANUAL_REQUEST. Raises an exception if no request is pending
- vbox.GATE_REQ_MANUAL_REQUEST (1) = Creates a new request based on the other args specified:
  vbox.LAPS_REQ_ENABLE = Enables lap timing processing
  
  vbox.LAPS_REQ_DISABLE = Disables lap timing processing
  
  vbox.LAPS_REQ_STANDING_START_ENABLE = Enables standing start mode
  
  vbox.LAPS_REQ_STANDING_START_DISABLE = Disables standing start mode
  
  vbox.LAPS_REQ_RESULTS_GET = Gets current lap timing results data. This returns:
  
  lap_end_systime(int) = System time stamp at end of the lap in milliseconds.
  
  last_lap_time_ms(int) = Most recent lap time in milliseconds.
  
  last_lap_dist_m(float) = Most recent lap distance in metres.
  
  last_ref_lap_time_ms(int) = Most recent reference lap time milliseconds.
  
  lap_start_tod_ms(int) = Current lap start time of day in milliseconds.
  
  lap_start_dist_m(float) = Current lap start distance in metres.
  
  ref_lap_time_ms(int) = Current lap reference lap time in milliseconds.
  
  lap_number(int) = Current lap number.
  
  vbox.LAPS_REQ_RESULTS_CLEAR = Clears the current lap results
  
  vbox.LAPS_REQ_LAP_CANCEL = Cancels current lap
  
  vbox.LAPS_REQ_STINT_START = Ends current stint if there is one and then starts a new one with the stint time set to 0.
  
  vbox.LAPS_REQ_STINT_END = Ends current stint and sets the stint time to -1.
  
  vbox.LAPS_REQ_STINT_GET = If a stint is active returns the period since it started in milliseconds. Otherwise returns None
  
  vbox.LAPS_REQ_RESULTS_GET_SPLIT = Gets the results for a split. This requires 2 other parameters:
  
  VBOX_LAP_SPLITS_CURRENT or VBOX_LAP_SPLITS_PREVIOUS and an Index.
  
  VBOX_LAP_SPLITS_CURRENT = Returns the current data for the specified split. Use while the split is active. Index must be in the range 0 <= Index < VBOX_MAX_SPLIT_GATES
  
  VBOX_LAP_SPLITS_PREVIOUS = Returns the previous data for the specified split. Use once the split has been exited. Index must be in the range 0 <= Index < VBOX_MAX_SPLITS
  
  Both return a tuple with the following fields:
  
  period_ms(int) = Split period in milliseconds.
  
  dist_m(float) = Split distance in metres.
  
  speed_end_mps(float) = Split end speed in m/s.
  
  gate_begin(int) = Identifier of the gate that started the split.
  
  gate_end(int) = Identifier of the gate that ended the split.