# Kvaser Air Bridge Utility CLI

## Version

V1.5.9

## Description
This utility tool is used to configure Kvaser Air Bridge devices or upgrade firmware.
Two basic variants exist: Air Bridge Light HS and Air Bridge which is a more advanced variant.
A Kvaser CAN interface is required to connect to the Air Bridge on an isolated CAN bus while employing this utility tool.
For the upgrade feature, the firmware is self-contained within the utility tool.
The release of this firmware corresponds to the release of the utility tool.
Note: the order of in which the arguments are entered is of no importance!
Note: The commands will always function if the device is powered ON AFTER the command has been issued.
Whether they work in other cases depends on the device variant and on how old the release is.
Please contact Kvaser support for more information.

## Arguments
      -h| --help                  help produces this informational help section
                                  e.g. "airbridge-utility-cli.exe --help"
                                  e.g. "airbridge-utility-cli.exe -h"

      -v| --verbose               verbose, has 4 levels 0(MINIMAL), 1(INFO/DEFAULT), 2(DEBUG), 3(VERBOSE).
                                  e.g. "airbridge-utility-cli.exe --verbose 3"
                                  e.g. "airbridge-utility-cli.exe -v 3"

     -ch| --channel               channel, the canlib channel that is connected to the desired Air Bridge.
                                  e.g. "airbridge-utility-cli.exe --channel 0"
                                  e.g. "airbridge-utility-cli.exe -ch 0"

      -R| --Reboot                Reboot, used to reboot an already powered up Air Bridge before issuing commands.
                                  Note: For Air Bridge Light HS, this will only work after it has been previously
                                  booted in Diagnostic mode.
                                  This will work for Air Bridge when the Management interface haven't yet been altered
                                  or the device has been previously booted in Diagnostic mode.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --Reboot"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -R"

      -D| --Diagnostic            Diagnostic, used to set Air Bridge into diagnostic mode.
                                  Note: Air Bridge will now have the Management Interface enabled with default RX/TX
                                  ID.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --Diagnostic"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -D"

      -c| --connect               connect, used to put device in bootloader mode upon startup and thereafter remain in
                                  this mode.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c"

     -LP| --List_Parameters       List_Parameters, used to read out parameters from the Air Bridge.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --List_Parameters"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D -LP"

   -SAB | --Set_APP_Bitrate       Set_APP_Bitrate, used to configure the startup bitrate on the Air Bridge.
                                  In addition to default bitrate A|Autobaud, there are 4 possible bitrates possible
                                  125, 250, 500 and 1000.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --Set_APP_Bitrate
                                  125"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D -SAB 125"
                                  Air Bridge (not Air Bridge Light) supports a sixth alternative C a Custom CAN
                                  Configuration which requires that relevant CAN parameters (bitrate, Tseg1, Tseg2, SJW
                                  and silent mode) to be set with the command "Set_APP_CAN_PARAMS".
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --Set_APP_Bitrate
                                  C"

    -SHP| --Set_Heartbeat_Period  Set_Heartbeat_Period, used to set the Heartbeat period of the device.
                                  The Heartbeat is by default inactivated (0) but can be configured to run periodically
                                  with periods between 100ms and 60000ms. The Heartbeat is persistent when power
                                  cycling a device.
                                  Note: A non-persistent Heartbeat is also available via the Management Interface.See
                                  the "Kvaser Air Bridge Management Interface description" for more information.
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_Heartbeat_Period 100"

   -SRFP| --Set_RF_PWR            Set_RF_PWR, used to configure the power level as Full, Low, UltraLow, Reset.
                                  Note: Configuration to Low or UltraLow power level requires careful consideration to
                                  how the Air Bridge devices are being used and their RF environment. Reset sets the
                                  power level to default value (Full).
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --Set_RF_PWR Low"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D -SRFP Low"

        | --upgrade               upgrade, used to upgrade a device to the firmware distributed in this utility tool.
                                  During the upgrade process DO NOT under any circumstances power OFF the device or
                                  abort the upgrade process! This may render the device unrecoverable!
                                  Note: A common error is not powering OFF target device before issuing command for
                                  upgrade!
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --upgrade"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c --upgrade"

    ================================================================================
           The section below does not apply for the Air Bridge Light HS
    ================================================================================

   -SRFR| --Set_RF_Role           Set_RF_Role, used to configure the role as P|Primary, S|Secondary.
                                  The role can be either Primary or Secondary. A Kvaser Air Bridge can establish a pair
                                  consisting of one Primary device and one Secondary device. Several Kvaser Air Bridge
                                  M12 devices can form a domain within which discovery and pairing is made possible.
                                  Such a domain set typically has one Primary device and several Secondary devices. A
                                  domain may however consist of multiple Primary devices and multiple Secondary
                                  devices.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --Set_RF_Role
                                  Primary"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D -SRFR Primary"

        | --Set_RF_Primary_Seed   Set_RF_Primary_Seed, used to configure the RF Primary Seed (4 hexadecimal numbers).
                                  The RF Primary seed is used internally in the Air Bridge to generate one out of two
                                  codes that define a private pairing domain for the Discovery/Pairing procedure within
                                  which the correct codes are required.
                                  Both a Primary seed and a Secondary seed need to be entered before the pairing domain
                                  is activated.
                                  Before that, the Air Bridge devices remain in the default pairing domain
                                  corresponding to seeds with seeds 0000.
                                  Note: Only devices with the same pairing codes (seed values) can be discovered,
                                  selected in Discovery/Pairing mode and paired.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic
                                  --Set_RF_Primary_Seed 0EFE"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_RF_Primary_Seed 01F1"

        | --Set_RF_Secondary_Seed Set_RF_Secondary_Seed, used to configure the RF Secondary Seed (4 hexadecimal
                                  numbers).
                                  The RF Secondary seed is used internally in the Air Bridge to generate one out of two
                                  codes that define a private pairing domain for the Discovery/Pairing procedure within
                                  which the correct codes are required.
                                  Both a Primary seed and a Secondary seed need to be entered before the pairing domain
                                  is activated.
                                  Before that, the Air Bridge devices remain in the default pairing domain
                                  corresponding to seeds with seeds 0000.
                                  Note: Only devices with the same pairing codes (seed values) can be discovered,
                                  selected in Discovery/Pairing mode and paired.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic
                                  --Set_RF_Primary_Seed 0FEF"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_RF_Secondary_Seed 0F1F"

        | --Set_Primary_Pairing   Set_Primary_Pairing, used as the first step in establishing a pairing between a
                                  primary and secondary device.
                                  Pairing is controlled by using the secondary device's RF ID as remote RF ID in the
                                  primary device and vice versa. The two paired devices must also have the same session
                                  ID configured.
                                  Note: This method requires that no mistakes are made regarding the use of RF ID and
                                  Session ID.
                                  The utility pairing method is initiated by performing this command on the Primary
                                  device before using the command "Set_Secondary_Pairing".
                                  When running this command a [Session ID] is generated. The Session ID is intended to
                                  be used as input to "Set_Secondary_Pairing".
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_Primary_Pairing [RFID Secondary]"

        | --Set_Secondary_Pairing Set_Secondary_Pairing, used as the second step in  establishing a pairing between a
                                  primary and secondary device.
                                  The utility pairing method is finalized by performing this command after using the
                                  command on the Secondary device after "Set_Primary_Pairing" on the Primary device, as
                                  the "Set_Primary_Pairing" generates the [Session ID] required for this command.
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_Secondary_Pairing [Session ID]
                                  [RFID Primary]"

    -SCV| --Set_Custom_Value      Set_Custom_Value, used to set the Custom value of the device.
                                  The Custom value is by default not configured(0), but can be set by the user as
                                  desired.
                                  Note that the value is 4 bytes long written in hex. For more information about Custom
                                  Value se the "Kvaser Air Bridge Management Interface description."
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_Custom_Value F0F1F2E0"

        | --Set_APP_CAN_PARAMS    Set_APP_CAN_PARAMS, used to set a custom CAN configuration for the Air Bridge.
                                  This includes relevant CAN parameters (bitrate, Tseg1, Tseg2, SJW and silent mode),
                                  for this to take effect "Custom CAN CFG" must be set. The order of parameters to this
                                  argument is crucial and should be "bitrate, Tseg1, Tseg2, SJW and silent mode"
                                  For example, with the 36MHz clock in Air Bridge, to achieve a custom bitrate of 105k
                                  use:
                                  "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --Set_APP_Bitrate C
                                  --Set_APP_CAN_PARAMS 105263 11 7 2 0"
                                  This sets a bitrate of 105263 bps, Tseg1 of 11, Tseg2 of 7, SJW of 2, and silent mode
                                  OFF (0).
                                  Note: There is a simple validator and it will check that the actual bitrate is within
                                  0.1% of the desired bitrate

        | --Set_CAN_Filter        Set_CAN_Filter, used to configure CAN filters (PASS filter based on ID and MASK) on
                                  the device.
                                  Upon creating the first filter, an additional filter will be configured automatically
                                  when the Management interface is enabled to allow data to be passed to the Interface.
                                  There is no check to determine if a filter already matches filters present on the
                                  device thus duplicate filters is a possibility, and if too many filters are set, a
                                  "buffer full"-NACK is generated.
                                  Note: The value is in hexadecimal format and in order to signal to the software that
                                  it is an extended CAN ID/MASK, a lowercase 'x' must be appended directly after both
                                  the CAN ID and the CAN MASK.

                                  - A binary 1 in the mask means the corresponding bit in the filter identifier is
                                  relevant.
                                  - A binary 0 in the mask means the corresponding bit in the filter identifier is not
                                  relevant.
                                  - A relevant binary 1 in the filter identifier means that the corresponding bit in
                                  the message identifier must be 1, for the message to be accepted and routed.
                                  - A relevant binary 0 in the filter identifier means that the corresponding bit in
                                  the message identifier must be 0, for the message to be accepted and routed.

                                  The order of parameters to this argument is crucial and should be "CAN ID and MASK"

                                  Creating a pass filter that exclusively allows only the extended ID 0x01123FFF:
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --Set_CAN_Filter
                                  01123FFFx 1FFFFFFFx"

                                  Creating multiple filters, one that exclusively allows std ID 0x123 and one that
                                  allows ext Id 0->15:
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --Set_CAN_Filter
                                  123 1FF --Set_CAN_Filter 00000000x 1FFFFFF0x"

        | --RM_CAN_Filter         RM_CAN_Filter, used to configure CAN filters (PASS filter based on ID and MASK) on
                                  the device.
                                  It is possible to remove all filters or filters matching the ID and MASK specified to
                                  the command
                                  Note: The value is in hexadecimal format and in order to signal to the software that
                                  it is an extended CAN ID/MASK, a lowercase 'x' must be appended directly after both
                                  the CAN ID and the CAN MASK.

                                  The order of parameters to this argument is crucial and should be "CAN ID and MASK"

                                  Remove all filters:
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --RM_CAN_Filter 0
                                  0"

                                  Remove multiple filters:
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --RM_CAN_Filter
                                  123 1FF --RM_CAN_Filter 45678x 1FFFFF00x"

    -------------------------------------------
           Management Interface - MI
    -------------------------------------------

        | --Set_MI_Enable         Set_MI_Enable, used to configure if the Management Interface Receiving CAN ID shall
                                  be  "Enable" or "Disable" on the device.
                                  The Management Interface is used for runtime configuration of the Air Bridge device
                                  and for control of the Air Bridge constellation, e.g. pairing and diagnostics.
                                  The Management Interface Sending ID is however always enabled providing the
                                  opportunity to subscribe to events even though the Management Interface Receiving ID
                                  is disabled.
                                  Note: Air Bridge will now have the Management Interface enabled with default
                                  Management Interface Receiving ID & Management Interface Sending ID unless
                                  configured.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic --Set_MI_Enable
                                  Enable"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_MI_Enable Enable"

        | --Set_MI_Receiving_ID   Set_MI_Receiving_ID, used to configure the Management Interface Receiving CAN ID on
                                  the device.
                                  Reset to default with 0, default value is 1BC78FFFx. Note: The value is in
                                  hexadecimal format and in order to signal to the software that it is an extended CAN
                                  ID, a lowercase 'x' must be appended directly after the CAN ID.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic
                                  --Set_MI_Receiving_ID 1BC78FFFx"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_MI_Receiving_ID 1BC78FFFx"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_MI_Receiving_ID 0"

        | --Set_MI_Sending_ID     Set_MI_Sending_ID, used to configure the Management Interface Sending CAN ID on the
                                  device.
                                  Reset to default with 0, default value is 1BFFF8F1x. Note: The value is in
                                  hexadecimal format and in order to signal to the software that it is an extended CAN
                                  ID, a lowercase 'x' must be appended directly after the CAN ID.
                                  e.g. "airbridge-utility-cli.exe --channel 0 --connect --Diagnostic
                                  --Set_MI_Sending_ID 1BFFF8F1x"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_MI_Sending_ID 1BFFF8F1x"
                                  e.g. "airbridge-utility-cli.exe -ch 0 -c -D --Set_MI_Sending_ID 0"

Included binaries in this build:
Application version: 2.4.1
Bootloader version: 2.4.0

