Skip to content

4. Library reference

Jump to bottom
domnulvlad edited this page Nov 1, 2024 · 14 revisions

Safe functions

  • Constructor - Creates an instance of the library.

    KLineKWP1281Lib(beginFunction, endFunction, sendFunction, receiveFunction, tx_pin, full_duplex, (debug_port))
    Parameters:
  beginFunction   -> [void (unsigned long baud)] function to begin communication on the serial port
  endFunction     -> [void ()                  ] function to end communication on the serial port
  sendFunction    -> [void (uint8_t data)      ] function to write a byte to the serial port
  receiveFunction -> [bool (uint8_t *data)     ] function to receive a byte from the serial port
  tx_pin          -> digital pin, coincides with the selected serial port's transmit pin
  full_duplex     -> flag indicating whether or not the selected serial interface can also read while sending
  (debug_port)    -> optionally provide a pointer to a Stream object (e.g. &Serial) to send debug information on

    Notes:
  *The return type and parameters taken by each callback function are explained above in brackets.
  *The receiveFunction must return false if no byte is available. If a byte is available, it is stored in the byte passed by pointer and it returns true.
  *If the serial interface is not able to receive while sending full_duplex should be set to false.
  *If, for some reason, the K-line does not echo back the bytes received, even if the serial interface is capable of receiving while sending, full_duplex should be set to false.

  • KWP1281debugFunction - Attaches a function to be called for debugging KWP1281 messages.

    KWP1281debugFunction(KWP1281debugFunction_type debug_function)
    Parameters:
  debug_function -> function to execute after sending/receiving a KWP1281 message, to show it

    Notes:
  *The function given here must return void and take the following parameters in the following order:
    - bool direction           -> true for inbound frames (received), false for outbound (sent)
    - uint8_t message_sequence -> message sequence number
    - uint8_t message_type     -> message type/command
    - uint8_t *data            -> message parameters (uint8_t pointer = byte array)
    - size_t length            -> amount of message parameters (amount of bytes in the data array)

  • custom5baudWaitFunction - Attaches a custom function to be executed while initializing the control module.

    custom5baudWaitFunction(custom5baudWaitFunction_type function)
    Parameters:
  function -> routine to execute after sending each bit during the 5-baud-init procedure

    Notes:
  *To achieve a baud rate of 5, the custom function must take 200 milliseconds.
  *It will be called a total of 10 times during initialization.
  *If no custom function is defined, a regular delay of 200ms will be used.

  • customErrorFunction - Attaches a custom function to be executed if an error occurs.

    customErrorFunction(customErrorFunction_type function)
    Parameters:
  function -> [void (uint8_t module, unsigned long baud)] function called when the connection is terminated because of an error

    Notes:
  *The previous parameters (module ID and baud rate) are provided, so the application can reconnect to the module on which the error occurred.
  *It will be called once, after a timeout occurs while waiting for data.
  *If no custom function is defined, the library will attempt to reconnect to the previously connected module.

  • attemptConnect - Attempts to connect to a module.

    attemptConnect(uint8_t module, unsigned long baud_rate, bool request_extra_identification)
    Parameters:
  module -> logical ID of the target module (engine-0x01, cluster-0x17 etc.)
  baud_rate -> communication speed (10400, 9600, 4800 etc.)
  request_extra_identification -> whether or not to request extra identification if it is available

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

    Notes:
  *The module's baud rate must be known beforehand. Trying to connect at an incorrect speed will always fail.
  *If a blocking delay of one second (if the connection fails) is not a problem, use connect(), which will run until successful.
  *If the module contains "extra identification", and request_extra_identification is set to false, that identification string will not be requested. The getExtraIdentification() function will return an empty string, but connection will be almost 1 second faster. So, if you are not interested in the extra identification string, always set this parameter false.

  • connect - Connects to a module.

    connect(uint8_t module, unsigned long baud_rate, bool request_extra_identification)
    Parameters:
  module -> logical ID of the target module (engine-0x01, cluster-0x17 etc.)
  baud_rate -> communication speed (10400, 9600, 4800 etc.)
  request_extra_identification -> whether or not to request extra identification if it is available

    Notes:
  *If establishing the connection fails, this function waits one second before retrying (blocking).
  *To avoid the blocking delay, use attemptConnect() and check its return value in order to execute custom code in case of failure.
  *If the connection cannot be established (i.e. the target module is unavailable), it will run indefinitely.
  *If the module contains "extra identification", and request_extra_identification is set to false, that identification string will not be requested. The getExtraIdentification() function will return an empty string, but connection will be almost 1 second faster. So, if you are not interested in the extra identification string, always set this parameter false.

  • update - Maintains the connection to the control module.

    update()
    Notes:
  *After ~500ms of inactivity without update(), the connection breaks.

  • disconnect - Disconnects from the control module.

    disconnect (bool wait_for_response)
    Parameters:
  wait_for_response -> whether or not to wait for a response

    Notes:
  *Some modules send a response to the disconnect request, some don't.
  *Setting wait_for_response to false will save responseTimeout milliseconds if the module doesn't respond to the disconnect request.

  • getPartNumber - Provides a string containing the module's VAG part number.

    getPartNumber()
    Returns:
  char* -> pointer to a character array

  • getIdentification - Provides a string containing the module's model name.

    getIdentification()
    Returns:
  char* -> pointer to a character array

  • getExtraIdentification - Provides a string containing the module's extra identification (such as a VIN).

    getExtraIdentification()
    Returns:
  char* -> pointer to a character array

    Notes:
  *If the module does not have any extra identification, the string will have a null size.

  • getCoding - Provides the module's coding value.

    getCoding()
    Returns:
  uint16_t -> the coding value

  • getWorkshopCode - Provides the module's WSC.

    getWorkshopCode()
    Returns:
  uint32_t -> the workshop code

  • readFaults - Reads the module's fault codes.

    readFaults(uint8_t &amount_of_fault_codes, uint8_t fault_code_buffer  , size_t fault_code_buffer_size)
    Parameters:
  amount_of_fault_codes  -> will contain the total number of fault codes
  fault_code_buffer      -> array into which to store the fault codes
  fault_code_buffer_size -> total (maximum) length of the given array

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

    Notes:
  *The DTCs are stored in the following order: DTC_H, DTC_L, DTC_ELABORATION.
  *The functions getFaultCode() and getFaultElaborationCode() can be used to easily get the fault+elaboration codes stored in the buffer by readFaults().
  *getFaultCode() and getFaultElaborationCode() are static functions so they do not require an instance to be used.

  • getFaultCode - Provides a fault code from a buffer filled by readFaults().

    getFaultCode(uint8_t fault_code_index, uint8_t amount_of_fault_codes, uint8_t fault_code_buffer[], size_t fault_code_buffer_size)
    Parameters:
  fault_code_index       -> index of the fault code that needs to be retrieved
  amount_of_fault_codes  -> total number of fault codes stored in the array (value passed as reference to readFaults())
  fault_code_buffer      -> array in which fault codes have been stored by readFaults()
  fault_code_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint16_t -> fault code

    Notes:
  *It is a static function so it does not require an instance to be used.

  • isOBDFaultCode - Determines whether or not a fault is of the "standard OBD" type.

    isOBDFaultCode(uint8_t fault_code_index, uint8_t amount_of_fault_codes, uint8_t fault_code_buffer[], size_t fault_code_buffer_size)
    Parameters (1):
  fault_code_index       -> index of the fault code whose type needs to be determined
  amount_of_fault_codes  -> total number of fault codes stored in the array (value passed as reference to readFaults())
  fault_code_buffer      -> array in which fault codes have been stored by readFaults()
  fault_code_buffer_size -> total size of the given array (provided with the sizeof() operator)

    isOBDFaultCode(uint16_t fault_code)
    Parameters (2):
  fault_code  -> fault code given by getFaultCode()

    Returns:
  bool -> whether or not the fault code is of standard OBD type

    Notes:
  *If a fault code is of standard OBD type, use getOBDFaultCode() to get a string containing the formatted code.
  *It is a static function so it does not require an instance to be used.

  • getOBDFaultCode - Formats a standard OBD fault code.

    getOBDFaultCode(uint8_t fault_code_index, uint8_t amount_of_fault_codes, uint8_t fault_code_buffer[], size_t fault_code_buffer_size, char str[], size_t string_size)
    Parameters (1):
  fault_code_index       -> index of the fault code whose formatted code needs to be retrieved
  amount_of_fault_codes  -> total number of fault codes stored in the array (value passed as reference to readFaults())
  fault_code_buffer      -> array in which fault codes have been stored by readFaults()
  fault_code_buffer_size -> total size of the given array (provided with the sizeof() operator)
  str                    -> string (character array) into which to copy the description string
  string_size            -> total size of the given array (provided with the sizeof() operator)

    getOBDFaultCode(uint16_t fault_code, char str[], size_t string_size)
    Parameters (2):
  fault_code  -> fault code given by getFaultCode()
  str         -> string (character array) into which to copy the description string
  string_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  char* -> the same character array provided (str)

    Notes:
  *If the provided fault code is not of the standard OBD type, an empty string is returned.
  *It is a static function so it does not require an instance to be used.

  • getFaultDescription - Provides a fault description string from a buffer filled by readFaults().

    getFaultDescription(uint8_t fault_code_index, uint8_t amount_of_fault_codes, uint8_t fault_code_buffer[], size_t fault_code_buffer_size, char str[], size_t string_size)
    Parameters (1):
  fault_code_index       -> index of the fault code whose description needs to be retrieved
  amount_of_fault_codes  -> total number of fault codes stored in the array (value passed as reference to readFaults())
  fault_code_buffer      -> array in which fault codes have been stored by readFaults()
  fault_code_buffer_size -> total size of the given array (provided with the sizeof() operator)
  str                    -> string (character array) into which to copy the description string
  string_size            -> total size of the given array (provided with the sizeof() operator)

    getFaultDescription(uint16_t fault_code, char str[], size_t string_size)
    Parameters (2):
  fault_code  -> fault code given by getFaultCode()
  str         -> string (character array) into which to copy the description string
  string_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  char* -> the same character array provided (str)

    Notes:
  *If the fault code is of the standard OBD type, the description may also contain the fault elaboration string at the end,
  after the ':' character.
  *It is a static function so it does not require an instance to be used.

  • getFaultDescriptionLength - Provides the length of the fault description string from a buffer filled by readFaults().

    getFaultDescriptionLength(uint8_t fault_code_index, uint8_t amount_of_fault_codes, uint8_t fault_code_buffer[], size_t fault_code_buffer_size)
    Parameters (1):
  fault_code_index       -> index of the fault code whose description needs to be retrieved
  amount_of_fault_codes  -> total number of fault codes stored in the array (value passed as reference to readFaults())
  fault_code_buffer      -> array in which fault codes have been stored by readFaults()
  fault_code_buffer_size -> total size of the given array (provided with the sizeof() operator)

    getFaultDescriptionLength(uint16_t fault_code)
    Parameters (2):
  fault_code  -> fault code given by getFaultCode()

    Returns:
  size_t -> string length

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getFaultElaborationCode - Provides a fault elaboration code from a buffer filled by readFaults().

    getFaultElaborationCode(uint8_t fault_code_index, uint8_t amount_of_fault_codes, uint8_t fault_code_buffer[], size_t fault_code_buffer_size)
    Parameters:
  fault_code_index       -> index of the fault code whose elaboration code needs to be retrieved
  amount_of_fault_codes  -> total number of fault codes stored in the array (value passed as reference to readFaults())
  fault_code_buffer      -> array in which fault codes have been stored by readFaults()
  fault_code_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> fault elaboration code

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getFaultElaboration - Provides a fault elaboration string from a buffer filled by readFaults().

    getFaultElaboration(bool &is_intermittent, uint8_t fault_code_index, uint8_t amount_of_fault_codes, uint8_t fault_code_buffer[], size_t fault_code_buffer_size, char str[], size_t string_size)
    Parameters (1):
  is_intermittent        -> whether or not the elaboration code indicated that the fault is "Intermittent"
  fault_code_index       -> index of the fault code whose elaboration needs to be retrieved
  amount_of_fault_codes  -> total number of fault codes stored in the array (value passed as reference to readFaults())
  fault_code_buffer      -> array in which fault codes have been stored by readFaults()
  fault_code_buffer_size -> total size of the given array (provided with the sizeof() operator)
  str                    -> string (character array) into which to copy the elaboration string
  string_size            -> total size of the given array (provided with the sizeof() operator)

    getFaultElaboration(bool &is_intermittent, uint8_t elaboration_code, char str[], size_t string_size)
    Parameters (2):
  is_intermittent  -> whether or not the elaboration code indicated that the fault is "Intermittent"
  elaboration_code -> elaboration code given by getFaultElaborationCode()
  str              -> string (character array) into which to copy the elaboration string
  string_size      -> total size of the given array (provided with the sizeof() operator)

    Returns:
  char* -> the same character array provided (str)

    Notes:
  *The fault elaboration may not be correct if the fault code is of standard OBD type.
  *Use the isOBDFaultCode() function to check the type of fault code.
  *If it is of standard OBD type, the elaboration will be contained in the description string,
  after the ':' character.
  *It is a static function so it does not require an instance to be used.

  • getFaultElaborationLength - Provides the length of the fault elaboration string from a buffer filled by readFaults().

    getFaultElaborationLength(uint8_t fault_code_index, uint8_t amount_of_fault_codes, uint8_t fault_code_buffer[], size_t fault_code_buffer_size)
    Parameters (1):
  fault_code_index       -> index of the fault code whose elaboration length needs to be retrieved
  amount_of_fault_codes  -> total number of fault codes stored in the array (value passed as reference to readFaults())
  fault_code_buffer      -> array in which fault codes have been stored by readFaults()
  fault_code_buffer_size -> total size of the given array (provided with the sizeof() operator)

    getFaultElaborationLength(uint8_t elaboration_code)
    Parameters (2):
  elaboration_code -> elaboration code given by getFaultElaborationCode()

    Returns:
  size_t -> string length

    Notes:
  *It is a static function so it does not require an instance to be used.

  • clearFaults - Clears the module's diagnostic trouble codes.

    clearFaults()
    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

    Notes:
  *Run readFaults() afterwards to check if it was effective.

  • readGroup - Reads a measurement group.

    readGroup(uint8_t &amount_of_measurements, uint8_t group, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters:
  amount_of_measurements  -> will contain the total number of measurements in the group
  group                   -> measurement group to read
  measurement_buffer      -> array into which to store the measurements
  measurement_buffer_size -> total (maximum) length of the given array

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR
    *GROUP_BASIC_SETTINGS -> buffer contains 10 raw values
    *GROUP_HEADER -> buffer contains the header of a header+body response
    *GROUP_BODY -> buffer contains the body of a header+body response

    Notes:
  *When receiving GROUP_HEADER, it should be "set aside", because its data will be needed when receiving GROUP_BODY.
  *Alternatively, always use readGroup() with a large enough buffer, and if you receive GROUP_HEADER, switch to a smaller buffer for receiving GROUP_BODY,
  because that response is generally 4 bytes long, compared to the header which can be even more than 80 bytes long.
  
  *For header+body responses, you need to use the function with suffixes "FromHeader" or "FromHeaderBody".
  *For example, instead of getMeasurementValue(), you will use getMeasurementValueFromHeaderBody().

  • getFormula - Retrieves the formula byte for a measurement from a buffer filled by readGroup().

    getFormula(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose formula must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> formula byte

    Notes:
  *Most measurements have 3 bytes. The formula is the first byte.
  *It is a static function so it does not require an instance to be used.

  • getNWb - Retrieves byte A for a measurement from a buffer filled by readGroup().

    getNWb(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose NWb must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> NWb (byte A)

    Notes:
  *Most measurements have 3 bytes. NWb is the second byte.
  *It is a static function so it does not require an instance to be used.

  • getMWb - Retrieves byte B for a measurement from a buffer filled by readGroup().

    getMWb(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose MWb must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> MWb (byte B)

    Notes:
  *Most measurements have 3 bytes. NWb is the third byte.
  *It is a static function so it does not require an instance to be used.

  • getMeasurementData - Retrieves the data for a measurement from a buffer filled by readGroup().

    getMeasurementData(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose data must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t* -> measurement data buffer

    Notes:
  *Usually, measurements contain 2 data bytes, but, in some special cases, they may contain more.
  *Find out how many bytes the measurement takes with the getMeasurementDataLength() function.
  *It is a static function so it does not require an instance to be used.

  • getMeasurementDataLength - Retrieves the data length for a measurement from a buffer filled by readGroup().

    getMeasurementDataLength(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose data length must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> measurement data length

    Notes:
  *Usually, measurements contain 2 data bytes, but, in some special cases, they may contain more.
  *It is a static function so it does not require an instance to be used.

  • getMeasurementType - Determines whether the value or the units string is significant for a measurement from a buffer filled by readGroup().

    getMeasurementType(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters (1):
  measurement_index       -> index of the measurement whose type must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    getMeasurementType(uint8_t formula)
    Parameters (2):
  formula -> byte returned by getFormula()

    Returns:
  measurementType ->
    UNKNOWN - requested measurement outside range
    VALUE   - get value with getMeasurementValue() and units with getMeasurementUnits()
    TEXT    - get text with getMeasurementText() and, sometimes, original value with getMeasurementValue()

    Notes:
  *If an invalid measurement_index is specified, the returned type is UNKNOWN.
  *Even if the measurement is of type TEXT, its value might contain the "origin" of the string, like a code or 16-bit value so it can be used without
  necessarily checking the text itself.
  *For example, for a clock measurement, the text string will contain "hh:mm", but the value will also be hh.mm (hours before decimal, minutes after).
  *It is a static function so it does not require an instance to be used.

  • getMeasurementValue - Calculates the actual value of a measurement from a buffer filled by readGroup().

    getMeasurementValue(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters (1):
  measurement_index       -> index of the measurement that needs to be calculated (0-3)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    getMeasurementValue(uint8_t formula, uint8_t measurement_data[], uint8_t measurement_data_length)
    Parameters (2):
  formula                 -> byte returned by getFormula()
  measurement_data        -> buffer returned by getMeasurementData()
  measurement_data_length -> byte returned by getMeasurementDataLength()

    getMeasurementValue(uint8_t formula, uint8_t NWb, uint8_t MWb)
    Parameters (3):
  formula -> byte returned by getFormula()
  NWb     -> byte returned by getNWb()
  MWb     -> byte returned by getMWb()

    Returns:
  double -> calculated value

    Notes:
  *If an invalid measurement_index is specified, the returned value is nan.
  *It is a static function so it does not require an instance to be used.

  • getMeasurementUnits - Provides a string containing the proper units for a measurement of type VALUE.

    getMeasurementUnits(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size, char str[], size_t string_size)
    Parameters (1):
  measurement_index       -> index of the measurement whose units must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)
  str                     -> string (character array) into which to copy the units
  string_size             -> total size of the given array (provided with the sizeof() operator)

    getMeasurementUnits(uint8_t formula, uint8_t measurement_data[], uint8_t measurement_data_length, char str[], size_t string_size)
    Parameters (2):
  formula                 -> byte returned by getFormula()
  measurement_data        -> buffer returned by getMeasurementData()
  measurement_data_length -> byte returned by getMeasurementDataLength()
  str                     -> string (character array) into which to copy the units
  string_size             -> total size of the given array (provided with the sizeof() operator)

    getMeasurementUnits(uint8_t formula, uint8_t NWb, uint8_t MWb, char str[], size_t string_size)
    Parameters (3):
  formula     -> byte returned by getFormula()
  NWb         -> byte returned by getNWb()
  MWb         -> byte returned by getMWb()
  str         -> string (character array) into which to copy the units
  string_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  char* -> the same character array provided (str)

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getMeasurementText - Provides a string containing the text for a measurement of type TEXT.

    getMeasurementText(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size, char str[], size_t string_size)
    Parameters (1):
  measurement_index       -> index of the measurement whose text must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)
  str                     -> string (character array) into which to copy the text
  string_size             -> total size of the given array (provided with the sizeof() operator)

    getMeasurementText(uint8_t formula, uint8_t measurement_data[], uint8_t measurement_data_length, char str[], size_t string_size)
    Parameters (2):
  formula                 -> byte returned by getFormula()
  measurement_data        -> buffer returned by getMeasurementData()
  measurement_data_length -> byte returned by getMeasurementDataLength()
  str                     -> string (character array) into which to copy the text
  string_size             -> total size of the given array (provided with the sizeof() operator)

    Returns:
  char* -> the same character array provided (str)

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getMeasurementTextLength - Provides the length of the text for a measurement of type TEXT.

    getMeasurementTextLength(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters (1):
  measurement_index       -> index of the measurement whose text length must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    getMeasurementTextLength(uint8_t formula, uint8_t measurement_data[], uint8_t measurement_data_length)
    Parameters (2):
  formula                 -> byte returned by getFormula()
  measurement_data        -> buffer returned by getMeasurementData()
  measurement_data_length -> byte returned by getMeasurementDataLength()

    Returns:
  size_t -> the length of the measurement's text

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getMeasurementDecimals - Determines the recommended decimal places of a measurement from a buffer filled by readGroup().

    getMeasurementDecimals(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t measurement_buffer[], size_t measurement_buffer_size)
    Parameters (1):
  measurement_index       -> index of the measurement whose recommended decimals must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which measurements have been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    getMeasurementDecimals(uint8_t formula)
    Parameters (2):
  formula -> byte returned by getFormula()

    Returns:
  uint8_t -> recommended decimal places

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getFormulaFromHeader - Retrieves the formula byte for a measurement from a buffer filled by readGroup() after it returned GROUP_HEADER.

    getFormulaFromHeader(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose formula must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which a header has been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> formula byte

    Notes:
  *Only use this function if readGroup() returned GROUP_HEADER.
  *It is a static function so it does not require an instance to be used.

  • getNWbFromHeader - Retrieves byte A for a measurement from a buffer filled by readGroup() after it returned GROUP_HEADER.

    getNWbFromHeader(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose NWb must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which a header has been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> NWb (byte A)

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getDataTableFromHeader - Retrieves the data table for a measurement from a buffer filled by readGroup() after it returned GROUP_HEADER.

    getDataTableFromHeader(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose data table must be retrieved (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which a header has been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t* -> measurement data table buffer

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getDataTableLengthFromHeader - Retrieves the data table length for a measurement from a buffer filled by readGroup() after it returned GROUP_HEADER.

    getDataTableLengthFromHeader(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose data table must be retrieved (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which a header has been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> measurement data table length

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getMeasurementTypeFromHeader - Determines the type of a measurement from a buffer filled by readGroup() after it returned GROUP_HEADER.

    getMeasurementTypeFromHeader(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size)
    Parameters:
  measurement_index       -> index of the measurement whose type must be determined (0-4)
  amount_of_measurements  -> total number of measurements stored in the array (value passed as reference to readGroup())
  measurement_buffer      -> array in which a header has been stored by readGroup()
  measurement_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  measurementType ->
    UNKNOWN - requested measurement outside range
    VALUE   - get value with getMeasurementValueFromHeaderBody() and units with getMeasurementUnitsFromHeaderBody()
    TEXT    - get text with getMeasurementTextFromHeaderBody() and, sometimes, original value with getMeasurementValueFromHeaderBody()

    Notes:
  *If an invalid measurement_index is specified, the returned type is UNKNOWN.
  *Even if the measurement is of type TEXT, its value might contain the "origin" of the string, like a code or 16-bit value so it can be used without
  necessarily checking the text itself.
  *For example, for a clock measurement, the text string will contain "hh:mm", but the value will also be hh.mm (hours before decimal, minutes after).
  *It is a static function so it does not require an instance to be used.

  • getMeasurementValueFromHeaderBody - Calculates the actual value of a measurement from two buffers filled by readGroup() after it returned GROUP_HEADER and GROUP_BODY.

    getMeasurementValueFromHeaderBody(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size, uint8_t amount_of_measurements_in_body, uint8_t body_buffer[], size_t body_buffer_size)
    Parameters:
  measurement_index                -> index of the measurement that needs to be calculated (0-3)
  amount_of_measurements_in_header -> total number of measurements stored in the header array (value passed as reference to readGroup(), returned GROUP_HEADER)
  header_buffer                    -> array in which a header has been stored by readGroup() (returned GROUP_HEADER)
  header_buffer_size               -> total size of the given header array (provided with the sizeof() operator)
  amount_of_measurements_in_body   -> total number of measurements stored in the body array (value passed as reference to readGroup(), returned GROUP_BODY)
  body_buffer                      -> array in which a body has been stored by readGroup() (returned GROUP_BODY)
  body_buffer_size                 -> total size of the given body array (provided with the sizeof() operator)

    Returns:
  double -> calculated value

    Notes:
  *If an invalid measurement_index is specified, the returned value is nan.
  *It is a static function so it does not require an instance to be used.

  • getMeasurementUnitsFromHeaderBody - Provides a string containing the proper units for a measurement of type VALUE from two buffers filled by readGroup() after it returned GROUP_HEADER and GROUP_BODY.

    getMeasurementUnitsFromHeaderBody(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size, uint8_t amount_of_measurements_in_body, uint8_t body_buffer[], size_t body_buffer_size, char str[], size_t string_size)
    Parameters:
  measurement_index                -> index of the measurement whose units must be determined (0-3)
  amount_of_measurements_in_header -> total number of measurements stored in the header array (value passed as reference to readGroup(), returned GROUP_HEADER)
  header_buffer                    -> array in which a header has been stored by readGroup() (returned GROUP_HEADER)
  header_buffer_size               -> total size of the given header array (provided with the sizeof() operator)
  amount_of_measurements_in_body   -> total number of measurements stored in the body array (value passed as reference to readGroup(), returned GROUP_BODY)
  body_buffer                      -> array in which a body has been stored by readGroup() (returned GROUP_BODY)
  body_buffer_size                 -> total size of the given body array (provided with the sizeof() operator)
  str                              -> string (character array) into which to copy the units
  string_size                      -> total size of the given array (provided with the sizeof() operator)

    Returns:
  char* -> the same character array provided (str)

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getMeasurementTextFromHeaderBody - Provides a string containing the text for a measurement of type TEXT from two buffers filled by readGroup() after it returned GROUP_HEADER and GROUP_BODY..

    getMeasurementTextFromHeaderBody(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size, uint8_t amount_of_measurements_in_body, uint8_t body_buffer[], size_t body_buffer_size, char str[], size_t string_size)
    Parameters:
  measurement_index                -> index of the measurement whose text must be determined (0-3)
  amount_of_measurements_in_header -> total number of measurements stored in the header array (value passed as reference to readGroup(), returned GROUP_HEADER)
  header_buffer                    -> array in which a header has been stored by readGroup() (returned GROUP_HEADER)
  header_buffer_size               -> total size of the given header array (provided with the sizeof() operator)
  amount_of_measurements_in_body   -> total number of measurements stored in the body array (value passed as reference to readGroup(), returned GROUP_BODY)
  body_buffer                      -> array in which a body has been stored by readGroup() (returned GROUP_BODY)
  body_buffer_size                 -> total size of the given body array (provided with the sizeof() operator)
  str                              -> string (character array) into which to copy the text
  string_size                      -> total size of the given array (provided with the sizeof() operator)

    Returns:
  char* -> the same character array provided (str)

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getMeasurementTextLengthFromHeaderBody - Provides the length of the text for a measurement of type TEXT from two buffers filled by readGroup() after it returned GROUP_HEADER and GROUP_BODY.

    getMeasurementTextLengthFromHeaderBody(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size, uint8_t amount_of_measurements_in_body, uint8_t body_buffer[], size_t body_buffer_size)
    Parameters:
  measurement_index                -> index of the measurement whose text length must be determined (0-3)
  amount_of_measurements_in_header -> total number of measurements stored in the header array (value passed as reference to readGroup(), returned GROUP_HEADER)
  header_buffer                    -> array in which a header has been stored by readGroup() (returned GROUP_HEADER)
  header_buffer_size               -> total size of the given header array (provided with the sizeof() operator)
  amount_of_measurements_in_body   -> total number of measurements stored in the body array (value passed as reference to readGroup(), returned GROUP_BODY)
  body_buffer                      -> array in which a body has been stored by readGroup() (returned GROUP_BODY)
  body_buffer_size                 -> total size of the given body array (provided with the sizeof() operator)

    Returns:
  size_t -> the length of the measurement's text

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getMeasurementDecimalsFromHeader - Determines the recommended decimal places of a measurement from a buffer filled by readGroup() after it returned GROUP_HEADER.

    getMeasurementDecimalsFromHeader(uint8_t measurement_index, uint8_t amount_of_measurements, uint8_t header_buffer[], size_t header_buffer_size)
    Parameters:
  measurement_index                -> index of the measurement whose recommended decimals must be determined (0-4)
  amount_of_measurements_in_header -> total number of measurements stored in the header array (value passed as reference to readGroup(), returned GROUP_HEADER)
  header_buffer                    -> array in which a header has been stored by readGroup() (returned GROUP_HEADER)
  header_buffer_size               -> total size of the given header array (provided with the sizeof() operator)

    Returns:
  uint8_t -> recommended decimal places

    Notes:
  *It is a static function so it does not require an instance to be used.

  • outputTests - Performs an output test.

    outputTests(uint16_t &current_output_test)
    Parameters:
  current_output_test -> will contain the currently running output test ID

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

    Notes:
  *Output tests are always performed in a sequence that cannot be changed.
  *To go through them all, use multiple calls of outputTests() until FAIL is returned.
  *The currently running test ID is stored in current_output_test.
  *Get a description of the currently running test with the getOutputTestDescription() function.

  • getOutputTestDescription - Provides the description string for an output test ID given by outputTests().

    getOutputTestDescription(uint16_t output_test, char str[], size_t string_size)
    Parameters:
  output_test -> output test ID, given by outputTests()
  str         -> string (character array) into which to copy the description string
  string_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  char* -> the same character array provided (str)

    Notes:
  *It is a static function so it does not require an instance to be used.

  • getOutputTestDescriptionLength - Provides the length of the description string for an output test ID given by outputTests().

    getOutputTestDescriptionLength(uint16_t output_test)
    Parameters:
  output_test -> output test ID, given by outputTests()

    Returns:
  size_t -> string length

    Notes:
  *It is a static function so it does not require an instance to be used.

Less safe functions

  • login - Performs a login operation.

    login(uint16_t login_code, uint32_t workshop_code)
    Parameters:
  login_code -> the login code
  workshop_code -> the CURRENT workshop code

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

  • recode - Recodes the module.

    recode(uint16_t coding, uint32_t workshop_code)
    Parameters:
  login_code -> the login code
  workshop_code -> the CURRENT workshop code

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

    Notes:
  *The new workshop code may only be applied if currently logged in with the previous code.

  • readAdaptation - Reads the value of an adaptation channel.

    readAdaptation(uint8_t channel, uint16_t &value)
    Parameters:
  channel -> adaptation channel to read
  value   -> will store the value read from the channel

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

  • testAdaptation - Tests whether or not a value would work for an adaptation channel.

    testAdaptation(uint8_t channel, uint16_t value)
    Parameters:
  channel -> adaptation channel to test the value on
  value   -> value to test

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

  • adapt - Changes the value of an adaptation channel.

    adapt(uint8_t channel, uint16_t value, uint32_t workshop_code)
    Parameters:
  channel       -> adaptation channel to modify
  value         -> value to store in the channel
  workshop_code -> WSC to use

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

    Notes:
  *Use testAdaptation() before adapt(), to ensure it's possible to use the value on the channel.

  • basicSetting - Performs a basic setting.

    basicSetting(uint8_t &amount_of_values, uint8_t group, uint8_t basic_setting_buffer[], size_t basic_setting_buffer_size)
    Parameters:
  amount_of_values          -> will contain the total number of values read from the basic setting group
  group                     -> basic setting group to activate/read
  basic_setting_buffer      -> array into which to store the received values
  basic_setting_buffer_size -> total (maximum) length of the given array

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

  • getBasicSettingValue - Provides a measured value from a buffer filled by basicSetting().

    getBasicSettingValue(uint8_t value_index, uint8_t amount_of_values, uint8_t basic_setting_buffer[] , size_t basic_setting_buffer_size)
    Parameters:
  value_index               -> index of the value that needs to be retrieved
  amount_of_values          -> total number of values stored in the array (value passed as reference to basicSetting())
  basic_setting_buffer      -> array in which fault codes have been stored by basicSetting()
  basic_setting_buffer_size -> total size of the given array (provided with the sizeof() operator)

    Returns:
  uint8_t -> value

    Notes:
  *It is a static function so it does not require an instance to be used.

  • readROM - Reads a chunk of ROM/EEPROM.

    readROM(uint8_t chunk_size, uint16_t start_address, size_t &bytes_received, uint8_t memory_buffer[], uint8_t memory_buffer_size)
    Parameters:
  chunk_size         -> how many bytes to read
  start_address      -> address from which to start reading
  bytes_received     -> how many bytes were read
  memory_buffer      -> array into which to store the bytes read
  memory_buffer_size -> total (maximum) length of the given array

    Returns:
  executionStatus -> whether or not the operation executed successfully
    *SUCCESS
    *FAIL
    *ERROR

Clone this wiki locally