Documentation: migrate system/i2c readme
This commit is contained in:
raiden00pl
Xiang Xiao
parent
ecbc8aa62c
commit
af8548097f
382
Documentation/applications/system/i2c/index.rst
Normal file
382
Documentation/applications/system/i2c/index.rst
Normal file
@ -0,0 +1,382 @@
|
||||
================
|
||||
``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::
|
||||
|
||||
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::
|
||||
|
||||
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::
|
||||
|
||||
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::
|
||||
|
||||
CONFIG_SYSTEM_I2C=y
|
||||
|
||||
2. Device-specific I2C driver support must be enabled::
|
||||
|
||||
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``).
|
||||
@ -8,6 +8,7 @@ System Libraries and NSH Add-Ons
|
||||
:titlesonly:
|
||||
|
||||
nxdiag/index.rst
|
||||
i2c/index.rst
|
||||
|
||||
- adb - ADB daemon application
|
||||
- argtable3 - ARGTABLE3 library
|
||||
|
||||
Loading…
Reference in New Issue
Block a user