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:
|
:titlesonly:
|
||||||
|
|
||||||
nxdiag/index.rst
|
nxdiag/index.rst
|
||||||
|
i2c/index.rst
|
||||||
|
|
||||||
- adb - ADB daemon application
|
- adb - ADB daemon application
|
||||||
- argtable3 - ARGTABLE3 library
|
- argtable3 - ARGTABLE3 library
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user