Add I2C README file
git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3934 42af7a65-404d-4744-a932-0658087f49c3
This commit is contained in:
patacongo
parent
49ffd7577a
commit
88e5e1d961
245
system/i2c/README.txt
Executable file
245
system/i2c/README.txt
Executable file
@ -0,0 +1,245 @@
|
|||||||
|
README File for the 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
|
||||||
|
========
|
||||||
|
|
||||||
|
o Help
|
||||||
|
o Common Line Form
|
||||||
|
o Common Command Options
|
||||||
|
- "Sticky" Options
|
||||||
|
- Environment variables
|
||||||
|
- Common Option Summary
|
||||||
|
o Command summary
|
||||||
|
- bus
|
||||||
|
- dev
|
||||||
|
- get
|
||||||
|
- set
|
||||||
|
|
||||||
|
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 [OPTIONS]
|
||||||
|
List devices: dev [OPTIONS] <first> <last>
|
||||||
|
Read register: get [OPTIONS]
|
||||||
|
Show help: help
|
||||||
|
Write register: set [OPTIONS] <value>
|
||||||
|
|
||||||
|
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
|
||||||
|
[-f freq] I2C frequency. Default: 400000 Current: 400000
|
||||||
|
|
||||||
|
NOTES:
|
||||||
|
o An environment variable like $PATH may be used for any argument.
|
||||||
|
o Arguments are "sticky". For example, once the I2C address is
|
||||||
|
specified, that address will be re-used until it is changed.
|
||||||
|
|
||||||
|
WARNING:
|
||||||
|
o 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 that in the "help" output above also shows both default value of
|
||||||
|
the I2C address (03 hex) and the current address value (also 03).
|
||||||
|
|
||||||
|
[-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.
|
||||||
|
|
||||||
|
[-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
|
||||||
|
discussethe 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 zero from each device.
|
||||||
|
|
||||||
|
If the device at an address responds, then this command will display the
|
||||||
|
address of the device. If the device does not respond, this command will
|
||||||
|
display "--". The resulting display is 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:
|
||||||
|
o The I2C dev command may have bad side effects on certain I2C devices.
|
||||||
|
For example, if could cause data loss in an EEPROM device.
|
||||||
|
o 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.
|
||||||
|
|
||||||
|
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 with 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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user