From b81b86e1f8c8a4aa0e3d85df8148152268f74260 Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Sat, 1 Jun 2013 17:25:16 -0600 Subject: Updates to README files --- apps/system/i2c/README.txt | 797 +++++++++++++++++++++++---------------------- 1 file changed, 400 insertions(+), 397 deletions(-) (limited to 'apps/system/i2c') diff --git a/apps/system/i2c/README.txt b/apps/system/i2c/README.txt index 7b432533b..1d6f22025 100644 --- a/apps/system/i2c/README.txt +++ b/apps/system/i2c/README.txt @@ -1,397 +1,400 @@ -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 [arguments] - Where is one of: - - Show help : ? - List buses : bus - List devices : dev [OPTIONS] - Read register : get [OPTIONS] [] - Show help : help - Write register: set [OPTIONS] [] - Verify access : verf [OPTIONS] [] - - 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 [arguments] - -Where 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 [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 -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] ------------------------------------------- - -The 'dev' command will attempt to identify all of the I2C devices on the -selected bus. The and arguments are 7-bit, hexadecimal -I2C addresses. This command will examine a range of addresses beginning -with and continuing through . 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 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] -------------------------------------- - - 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 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] [] ------------------------------------------------------- - - 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 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) +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 [arguments] + Where is one of: + + Show help : ? + List buses : bus + List devices : dev [OPTIONS] + Read register : get [OPTIONS] [] + Show help : help + Write register: set [OPTIONS] [] + Verify access : verf [OPTIONS] [] + + 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 [arguments] + +Where 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 [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 +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] +------------------------------------------ + +The 'dev' command will attempt to identify all of the I2C devices on the +selected bus. The and arguments are 7-bit, hexadecimal +I2C addresses. This command will examine a range of addresses beginning +with and continuing through . 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 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] +------------------------------------- + + 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 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] [] +------------------------------------------------------ + + 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 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. Application configuration. + + Using 'make menuconfig', select the i2c tool. The following + definition should appear in your .config file: + + CONFIG_SYSTEM_I2C=y + + Deprecated. In the older style configuration, there would have been + an appconfig file containing the path to the I2C tool directory like: + + CONFIGURE_APPS += system/i2c + +2. 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). + +3. 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. + +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) -- cgit v1.2.3