1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
|
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_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 - 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
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 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. 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 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_BUILD_PROTECTED
or CONFIG_BUILD_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_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: 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)
|