How Do I Interpret and Make the Best Use of Code Status and Code Error Returns?

Viewing data on monitors

Photo by Kevin Ku

Question from the Customer:

I have the Aardvark I2C/SPI Host Adapter and I am learning to use it with Control Center Serial Software and Aardvark Software API.

I have been able to read address 0x00, value 0xA8, when using the Control Center Serial Software; however, I have not been able to get those results with the script I wrote using the API software. Instead, I see value 0 and status 3. Here is the section of code that I am trying to use. Can you please take a look and advise how to improve the results?

port  = atoi(argv[1]);
    addr  = (u08)strtol(argv[2], 0, 0);
    reg   = (u08)strtol(argv[3], 0, 0);

    // Open the device
    handle = aa_open(port);
    if (handle <= 0) {
        printf("Unable to open Aardvark device on port %d\n", port);
        printf("Error code = %d\n", handle);
        return 1;

    // Ensure that the I2C subsystem is enabled
    aa_configure(handle, AA_CONFIG_SPI_I2C);
    // Enable the I2C bus pullup resistors (2.2k resistors).
    // This command is only effective on v2.0 hardware or greater.
    // The pullup resistors on the v1.02 hardware are enabled by default.

    aa_i2c_pullup(handle, AA_I2C_PULLUP_BOTH);

    // Enable the Aardvark adapter's power pins.
    // This command is only effective on v2.0 hardware or greater.
    // The power pins on the v1.02 hardware are not enabled by default.
    aa_target_power(handle, AA_TARGET_POWER_BOTH);

    // Setup the bitrate
    bitrate = aa_i2c_bitrate(handle, I2C_BITRATE);
    printf("Bitrate set to %d kHz\n", bitrate);
    status = aa_i2c_write_ext(handle, addr, AA_I2C_NO_FLAGS, num_bytes, &reg, &num_written);
    printf("aa_i2c_write_ext status %s\n", aa_status_string(status));
    status = aa_i2c_read_ext(handle, addr, AA_I2C_NO_FLAGS, num_bytes, &value, &num_read);
    printf("status %d\n", status);
    printf("aa_i2c_read_ext status %s\n", aa_status_string(status));
    printf("value %d\n", value);

    // Close the device


Response from Technical Support:

Thanks for your question! A return value could indicate an error or status code. In your case, the return value of 3 is an extended status code for read and write transactions, not an indication of an error. Also, the AA_I2C_STATUS_DATA_NACK is a valid flag for the function aa_i2c_write_ext, with the extended status code 4.


API Status and Error Codes

Status and error codes are defined in the user manual. We recommend you have a look on Table 6 of the Aardvark I2C/SPI Host Adapter User Manual.

The codes that are significant with your API script:

  • The first row in Table 7 is status code 1.
  • The 6th row is status code 6.
  • The 7th row is status code 7.

When aa_i2c_write_ext returns the status code 3, which indicates AA_I2C_STATUS_SLA_NACK, the Aardvark adapter did not receive acknowledgment for the requested slave address during a master operation.


Flags and Master Write

For a master write operation, the AA_I2C_STATUS_DATA_NACK flag can be useful in the following situation:

  • Normally, the I2C master writes to the slave until the slave issues a NACK or the requested number of bytes have been written.
  • If the master wishes to write 10 bytes, the I2C slave issues either an ACK or NACK on the tenth byte without affecting the total number of bytes transferred. Hence, the aa_i2c_write function cannot provide the caller with the information that the 10th byte was acknowledged (ACK) or not acknowledged (NACK).

However, if the aa_i2c_write_ext function is used, the status code will distinguish the two scenarios. This status information could be useful for further communication with the slave device in your setup.


Hardware Recommendations for Signal Performance

The hardware connection between the Aardvark adapter and the target device affects the ability to send, receive, and acknowledge messages. To support signal performance, we strongly recommend using short I2C/SPI cables, about 5” in length. A long cable length affects the signal integrity and the operational speed. The I2C/SPI bus does not have any inherent distance capability and excessive cable lengths can cause signal corruption.


More Information - How To and Why

We provide information and guidelines online about all our products, including applications for the Aardvark adapter and API.

We also have several articles in our blog section that provide solutions for timeout and bus lock, synchronizing multiple adapters on a production floor, and more.

We hope this answers your questions. Additional resources that you may find helpful include the following:

If you want more information, feel free to contact us with your questions, or request a demo that applies to your application.