diff options
Diffstat (limited to 'apps/system/i2c/README.txt')
| -rwxr-xr-x | apps/system/i2c/README.txt | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/apps/system/i2c/README.txt b/apps/system/i2c/README.txt new file mode 100755 index 000000000..97801bcaa --- /dev/null +++ b/apps/system/i2c/README.txt @@ -0,0 +1,397 @@ +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 System Requirements
+ - I2C Driver
+ - Configuration Options
+ o Help
+ o Common Line Form
+ o Common Command Options
+ - "Sticky" Options
+ - Environment variables
+ - Common Option Summary
+ o Command summary
+ - bus
+ - dev
+ - get
+ - set
+ - verf
+ o I2C Build Configuration
+ - NuttX Configuration Requirements
+ - I2C Tool Configuration Options
+
+System Requirements
+===================
+
+I2C Driver
+----------
+In order to use the I2C driver, you system -- in particular, your I2C driver --
+must meet certain requirements:
+
+1. It support calling up_i2cinitialize() numerous times, resetting the I2C
+ hardware on each (initial) time. up_i2cuninitialize() will be called after
+ each call to up_i2cinitialize() to free any resources and disable the I2C.
+2. up_i2cinitialize must accept any interface number without crashing. It
+ must simply return NULL if the device is not supported.
+3. The I2C driver must support the transfer method (CONFIG_I2C_TRANSFER=y).
+
+The I2C tool is designed to be implemented as a NuttShell (NSH) add-on. Read
+the apps/nshlib/README.txt file for information about add-ons.
+
+Configuration Options
+---------------------
+CONFIG_I2CTOOL_BUILTIN - 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 - Minium 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] [<repititions>]
+ Show help : help
+ Write register: set [OPTIONS] <value> [<repititions>]
+ Verify access : verf [OPTIONS] <value> [<repititions>]
+
+ 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 repititions. Default: NO Current: NO
+ [-f freq] I2C frequency. Default: 100000 Current: 100000
+
+ 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 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 repititions. 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 repitition.
+
+[-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
+discusse 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 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.
+
+ An optional <repititions> 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 repitions. 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 <repititions> 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 repitions. 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> [<repititions>]
+------------------------------------------------------
+
+ 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 <repititions> 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 repitions. 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. Device-specific I2C support must be enabled. The I2C tool will call the
+ platform-specific function up_i2cinitialize() to get instances of the
+ I2C interface and the platform-specific function up_i2cuninitialize()
+ to discard instances of the I2C interface.
+
+ NOTE 1: The I2C interface is defined in include/nuttx/i2c.h.
+
+ NOTE 2: This I2C tool uses direct I2C device interfaces. As such, it
+ relies on internal OS interfaces that are not normally available to a
+ user-space program. As a result, the I2C tool cannot be used if a
+ NuttX is built as a protected, supervisor kernel (CONFIG_NUTTX_KERNEL).
+
+2. I2C driver configuration
+
+ The CONFIG_I2C_TRANSFER option must also be set in your 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_I2C_TRANSFER=y
+
+ NOTE: CONFIG_I2C_TRANSFER adds extra methods to the I2C interface.
+ Not all I2C interfaces support these extra methods. If your platform's
+ I2C driver does not support these extra methods, then you cannot use
+ the I2C tool unless you extend the support in your platform I2C
+ driver.
+
+3. Application configuration.
+
+ The path to the I2C tool directory must also be set in your NuttX
+ application configuration. This application configuration is the
+ appconfig file in your configuration directory that is copied to the
+ NuttX application directory as .config when NuttX is configured.
+
+ CONFIGURE_APPS += system/i2c
+
+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_I2CTOOL_BUILTIN: 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: Minium 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)
|