388 lines
14 KiB
Markdown
388 lines
14 KiB
Markdown
# System / `i2c` I2C Tool
|
||
|
||
The I2C tool provides a way to debug I2C related problems. This README file will
|
||
provide usage information for the I2C tools.
|
||
|
||
## Contents
|
||
|
||
- System Requirements
|
||
- I2C Driver
|
||
- Configuration Options
|
||
- Help
|
||
- Common Line Form
|
||
- Common Command Options
|
||
- _Sticky_ Options
|
||
- Environment variables
|
||
- Common Option Summary
|
||
- Command summary
|
||
- `bus`
|
||
- `dev`
|
||
- `get`
|
||
- `set`
|
||
- `verf`
|
||
- I2C Build Configuration
|
||
- NuttX Configuration Requirements
|
||
- I2C Tool Configuration Options
|
||
|
||
## System Requirements
|
||
|
||
The I2C tool is designed to be implemented as a NuttShell (NSH) add-on. Read the
|
||
`apps/nshlib/README.md` file for information about add-ons.
|
||
|
||
### Configuration Options
|
||
|
||
- `CONFIG_NSH_BUILTIN_APPS` – Build the tools as an NSH built-in command.
|
||
- `CONFIG_I2CTOOL_MINBUS` – Smallest bus index supported by the hardware
|
||
(default `0`).
|
||
- `CONFIG_I2CTOOL_MAXBUS` – Largest bus index supported by the hardware
|
||
(default `3`).
|
||
- `CONFIG_I2CTOOL_MINADDR` – Minimum device address (default: `0x03`).
|
||
- `CONFIG_I2CTOOL_MAXADDR` – Largest device address (default: `0x77`).
|
||
- `CONFIG_I2CTOOL_MAXREGADDR` – Largest register address (default: `0xff`).
|
||
- `CONFIG_I2CTOOL_DEFFREQ` – Default frequency (default: `4000000`).
|
||
|
||
## Help
|
||
|
||
First of all, the I2C tools supports a pretty extensive help output. That help
|
||
output can be view by entering either:
|
||
|
||
```
|
||
nsh> i2c help
|
||
```
|
||
|
||
or
|
||
|
||
```
|
||
nsh> i2c ?
|
||
```
|
||
|
||
Here is an example of the help output. I shows the general form of the command
|
||
line, the various I2C commands supported with their unique command line options,
|
||
and a more detailed summary of the command I2C command options.
|
||
|
||
```
|
||
nsh> i2c help
|
||
|
||
Usage: i2c <cmd> [arguments]
|
||
Where <cmd> is one of:
|
||
|
||
Show help : ?
|
||
List buses : bus
|
||
List devices : dev [OPTIONS] <first> <last>
|
||
Read register : get [OPTIONS] [<repetitions>]
|
||
Show help : help
|
||
Write register: set [OPTIONS] <value> [<repetitions>]
|
||
Verify access : verf [OPTIONS] <value> [<repetitions>]
|
||
|
||
Where common _sticky_ OPTIONS include:
|
||
[-a addr] is the I2C device address (hex). Default: 03 Current: 03
|
||
[-b bus] is the I2C bus number (decimal). Default: 1 Current: 1
|
||
[-r regaddr] is the I2C device register address (hex). Default: 00 Current: 00
|
||
[-w width] is the data width (8 or 16 decimal). Default: 8 Current: 8
|
||
[-s|n], send/don't send start between command and data. Default: -n Current: -n
|
||
[-i|j], Auto increment|don't increment regaddr on repetitions. Default: NO Current: NO
|
||
[-f freq] I2C frequency. Default: 100000 Current: 100000
|
||
```
|
||
|
||
**Notes**:
|
||
|
||
- An environment variable like `$PATH` may be used for any argument.
|
||
- Arguments are _sticky_. For example, once the I2C address is specified, that
|
||
address will be re-used until it is changed.
|
||
|
||
**Warning**:
|
||
|
||
- The I2C dev command may have bad side effects on your I2C devices. Use only at
|
||
your own risk.
|
||
|
||
## Command Line Form
|
||
|
||
The I2C is started from NSH by invoking the `i2c` command from the NSH command
|
||
line. The general form of the `i2c` command is:
|
||
|
||
```shell
|
||
i2c <cmd> [arguments]
|
||
```
|
||
|
||
Where `<cmd>` is a _sub-command_ and identifies one I2C operations supported by
|
||
the tool. `[arguments]` represents the list of arguments needed to perform the
|
||
I2C operation. Those arguments vary from command to command as described below.
|
||
However, there is also a core set of common `OPTIONS` supported by all commands.
|
||
So perhaps a better representation of the general I2C command would be:
|
||
|
||
```shell
|
||
i2c <cmd> [OPTIONS] [arguments]
|
||
```
|
||
|
||
Where `[OPTIONS]` represents the common options and and arguments represent the
|
||
operation-specific arguments.
|
||
|
||
## Common Command Options
|
||
|
||
### _Sticky_ Options
|
||
|
||
In order to interact with I2C devices, there are a number of I2C parameters that
|
||
must be set correctly. One way to do this would be to provide to set the value
|
||
of each separate command for each I2C parameter. The I2C tool takes a different
|
||
approach, instead: The I2C configuration can be specified as a (potentially
|
||
long) sequence of command line arguments.
|
||
|
||
These arguments, however, are _sticky_. They are sticky in the sense that once
|
||
you set the I2C parameter, that value will remain until it is reset with a new
|
||
value (or until you reset the board).
|
||
|
||
### Environment Variables
|
||
|
||
**Note** also that if environment variables are not disabled (by
|
||
`CONFIG_DISABLE_ENVIRON=y`), then these options may also be environment
|
||
variables. Environment variables must be preceded with the special character
|
||
`$`. For example, `PWD` is the variable that holds the current working directory
|
||
and so `$PWD` could be used as a command line argument. The use of environment
|
||
variables on the I2C tools command is really only useful if you wish to write
|
||
NSH scripts to execute a longer, more complex series of I2C commands.
|
||
|
||
### Common Option Summary
|
||
|
||
- `[-a addr]` is the I2C device address (hex). Default: `03` Current: `03`
|
||
|
||
The `[-a addr]` sets the I2C device address. The valid range is `0x03` through
|
||
`0x77` (this valid range is controlled by the configuration settings
|
||
`CONFIG_I2CTOOL_MINADDR` and `CONFIG_I2CTOOL_MAXADDR`). If you are working
|
||
with the same device, the address needs to be set only once.
|
||
|
||
All I2C address are 7-bit, hexadecimal values.
|
||
|
||
**Note 1**: Notice in the `help` output above it shows both default value of the
|
||
I2C address (`03` hex) and the current address value (also `03` hex).
|
||
|
||
**Note 2**: Sometimes I2C addresses are represented as 8-bit values (with bit zero
|
||
indicating a read or write operation). The I2C tool uses a 7-bit
|
||
representation of the address with bit 7 unused and no read/write indication
|
||
in bit 0. Essentially, the 7-bit address is like the 8-bit address shifted
|
||
right by 1.
|
||
|
||
**Note 3**: Most I2C bus controllers will also support 10-bit addressing. That
|
||
capability has not been integrated into the I2C tool as of this writing.
|
||
|
||
- `[-b bus]` is the I2C bus number (decimal). Default: `1` Current: `1`
|
||
|
||
Most devices support multiple I2C devices and also have unique bus numbering.
|
||
This option identifies which bus you are working with now. The valid range of
|
||
bus numbers is controlled by the configuration settings
|
||
`CONFIG_I2CTOOL_MINBUS` and `CONFIG_I2CTOOL_MAXBUS`.
|
||
|
||
The bus numbers are small, decimal numbers.
|
||
|
||
- `[-r regaddr]` is the I2C device register address (hex). Default: `00`
|
||
Current: `00`
|
||
|
||
The I2C set and get commands will access registers on the I2C device. This
|
||
option selects the device register address (sometimes called the sub-address).
|
||
This is an 8-bit hexadecimal value. The maximum value is determined by the
|
||
configuration setting `CONFIG_I2CTOOL_MAXREGADDR`.
|
||
|
||
- `[-w width] `is the data width (8 or 16 decimal). Default: `8` Current: `8`
|
||
|
||
Device register data may be 8-bit or 16-bit. This options selects one of those
|
||
two data widths.
|
||
|
||
- `[-s|n]`, send/don't send start between command and data. Default: `-n`
|
||
Current: `-n`
|
||
|
||
This determines whether or not there should be a new I2C START between sending
|
||
of the register address and sending/receiving of the register data.
|
||
|
||
- `[-i|j]`, Auto increment|don't increment `regaddr` on repetitions. Default:
|
||
`NO` Current: `NO`
|
||
|
||
On commands that take a optional number of repetitions, the option can be used
|
||
to temporarily increment the `regaddr` value by one on each repetition.
|
||
|
||
- `[-f freq]` I2C frequency. Default: `400000` Current: `400000`
|
||
|
||
The `[-f freq]` sets the frequency of the I2C device.
|
||
|
||
## Command Summary
|
||
|
||
We have already seen the I2C help (or `?`) commands above. This section will
|
||
discuss the remaining commands.
|
||
|
||
### List buses: `bus [OPTIONS]`
|
||
|
||
This command will simply list all of the configured I2C buses and indicate which
|
||
are supported by the driver and which are not:
|
||
|
||
```
|
||
BUS EXISTS?
|
||
Bus 1: YES
|
||
Bus 2: NO
|
||
```
|
||
|
||
The valid range of bus numbers is controlled by the configuration settings
|
||
`CONFIG_I2CTOOL_MINBUS` and `CONFIG_I2CTOOL_MAXBUS`.
|
||
|
||
### List devices: `dev [OPTIONS] <first> <last>`
|
||
|
||
The `dev` command will attempt to identify all of the I2C devices on the
|
||
selected bus. The `<first>` and `<last>` arguments are 7-bit, hexadecimal I2C
|
||
addresses. This command will examine a range of addresses beginning with
|
||
`<first>` and continuing through `<last>`. It will request the value of register
|
||
address zero from each device.
|
||
|
||
The register address of zero is always used by default. The previous _sticky_
|
||
register address is ignored. Some devices may not respond to ergister address
|
||
zero, however. To work around this, you can provide a new _sticky_ register
|
||
address on the command as an option to the 'dev' command. Then that new _sticky_
|
||
register address will be used instead of the address zero.
|
||
|
||
If the device at an I2C address responds to the read request, then the `dev`
|
||
command will display the I2C address of the device. If the device does not
|
||
respond, this command will display `--`. The resulting display looks like:
|
||
|
||
```shell
|
||
nsh> i2c dev 03 77
|
||
```
|
||
|
||
```
|
||
0 1 2 3 4 5 6 7 8 9 a b c d e f
|
||
00: -- -- -- -- -- -- -- -- -- -- -- -- --
|
||
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||
40: -- -- -- -- -- -- -- -- -- 49 -- -- -- -- -- --
|
||
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
|
||
70: -- -- -- -- -- -- -- --
|
||
```
|
||
|
||
Warnings:
|
||
- The I2C dev command may have bad side effects on certain I2C devices. For
|
||
example, if could cause data loss in an EEPROM device.
|
||
- The I2C dev command also depends upon the underlying behavior of the I2C
|
||
driver. How does the driver respond to addressing failures?
|
||
|
||
### Read register: `get [OPTIONS]`
|
||
|
||
This command will read the value of the I2C register using the selected I2C
|
||
parameters in the common options. No other arguments are required.
|
||
|
||
This command with write the 8-bit address value then read an 8- or 16-bit data
|
||
value from the device. Optionally, it may re-start the transfer before obtaining
|
||
the data.
|
||
|
||
An optional `<repetitions>` argument can be supplied to repeat the read
|
||
operation an arbitrary number of times (up to 2 billion). If auto-increment is
|
||
select (`-i`), then the register address will be temporarily incremented on each
|
||
repetitions. The increment is temporary in the since that it will not alter the
|
||
_sticky_ value of the register address.
|
||
|
||
On success, the output will look like the following (the data value read will be
|
||
shown as a 4-character hexadecimal number if the 16-bit data width option is
|
||
selected).
|
||
|
||
```
|
||
READ Bus: 1 Addr: 49 Subaddr: 04 Value: 96
|
||
```
|
||
|
||
All values (except the bus numbers) are hexadecimal.
|
||
|
||
### Write register: `set [OPTIONS] <value>`
|
||
|
||
This command will write a value to an I2C register using the selected I2C
|
||
parameters in the common options. The value to write must be provided as the
|
||
final, hexadecimal value. This value may be an 8-bit value (in the range
|
||
`00`-`ff`) or a 16-bit value (in the range `0000`-`ffff`), depending upon the
|
||
selected data width.
|
||
|
||
This command will write the 8-bit address value then write the 8- or 16-bit data
|
||
value to the device. Optionally, it may re-start the transfer before writing the
|
||
data.
|
||
|
||
An optional `<repetitions>` argument can be supplied to repeat the write
|
||
operation an arbitrary number of times (up to 2 billion). If auto-increment is
|
||
select (`-i`), then the register address will be temporarily incremented on each
|
||
repetitions. The increment is temporary in the since that it will not alter the
|
||
_sticky_ value of the register address.
|
||
|
||
On success, the output will look like the following (the data value written will
|
||
be shown as a 4-character hexadecimal number if the 16-bit data width option is
|
||
selected).
|
||
|
||
```
|
||
WROTE Bus: 1 Addr: 49 Subaddr: 04 Value: 96
|
||
```
|
||
|
||
All values (except the bus numbers) are hexadecimal.
|
||
|
||
### Verify access: `verf [OPTIONS] <value> [<repetitions>]`
|
||
|
||
|
||
This command combines writing and reading from an I2C device register. It will
|
||
write a value to an will write a value to an I2C register using the selected I2C
|
||
parameters in the common options just as described for tie `set` command. Then
|
||
this command will read the value back just as described with the `get` command.
|
||
Finally, this command will compare the value read and against the value written
|
||
and emit an error message if they do not match.
|
||
|
||
If no value is provided, then this command will use the register address itself
|
||
as the data, providing for a address-in-address test.
|
||
|
||
An optional `<repetitions>` argument can be supplied to repeat the verify
|
||
operation an arbitrary number of times (up to 2 billion). If auto-increment is
|
||
select (`-i`), then the register address will be temporarily incremented on each
|
||
repetitions. The increment is temporary in the since that it will not alter the
|
||
`sticky` value of the register address.
|
||
|
||
On success, the output will look like the following (the data value written will
|
||
be shown as a 4-character hexadecimal number if the 16-bit data width option is
|
||
selected).
|
||
|
||
```
|
||
VERIFY Bus: 1 Addr: 49 Subaddr: 04 Wrote: 96 Read: 92 FAILURE
|
||
```
|
||
|
||
All values (except the bus numbers) are hexadecimal.
|
||
|
||
## I2C Build Configuration
|
||
|
||
### NuttX Configuration Requirements
|
||
|
||
The I2C tools requires the following in your NuttX configuration:
|
||
|
||
1. Application configuration.
|
||
|
||
Using `make menuconfig`, select the i2c tool. The following definition should
|
||
appear in your `.config` file:
|
||
|
||
```conf
|
||
CONFIG_SYSTEM_I2C=y
|
||
```
|
||
|
||
2. Device-specific I2C driver support must be enabled:
|
||
|
||
```conf
|
||
CONFIG_I2C_DRIVER=y
|
||
```
|
||
|
||
The I2C tool will then use the I2C character driver to access the I2C bus.
|
||
These devices will reside at `/dev/i2cN` where `N` is the I2C bus number.
|
||
|
||
**Note**: The I2C driver `ioctl` interface is defined in
|
||
`include/nuttx/i2c/i2c_master.h`.
|
||
|
||
### I2C Tool Configuration Options
|
||
|
||
The default behavior of the I2C tool can be modified by the setting the options
|
||
in the NuttX configuration. This configuration is the `defconfig` file in your
|
||
configuration directory that is copied to the NuttX top-level directory as
|
||
`.config` when NuttX is configured.
|
||
|
||
- `CONFIG_NSH_BUILTIN_APPS` – Build the tools as an NSH built-in command.
|
||
- `CONFIG_I2CTOOL_MINBUS` – Smallest bus index supported by the hardware
|
||
(default `0`).
|
||
- `CONFIG_I2CTOOL_MAXBUS` – Largest bus index supported by the hardware
|
||
(default `3`).
|
||
- `CONFIG_I2CTOOL_MINADDR` – Minimum device address (default: `0x03`).
|
||
- `CONFIG_I2CTOOL_MAXADDR` – Largest device address (default: `0x77`).
|
||
- `CONFIG_I2CTOOL_MAXREGADDR` – Largest register address (default: `0xff`).
|
||
- `CONFIG_I2CTOOL_DEFFREQ` – Default frequency (default: `4000000`).
|