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
|
.. currentmodule:: machine
.. _machine.I2CTarget:
class I2CTarget -- an I2C target device
=======================================
An I2C target is a device which connects to an I2C bus and is controlled by an
I2C controller. I2C targets can take many forms. The :class:`machine.I2CTarget`
class implements an I2C target that can be configured as a memory/register device,
or as an arbitrary I2C device by using callbacks (if supported by the port).
Example usage for the case of a memory device::
from machine import I2CTarget
# Create the backing memory for the I2C target.
mem = bytearray(8)
# Create an I2C target. Depending on the port, extra parameters
# may be required to select the peripheral and/or pins to use.
i2c = I2CTarget(addr=67, mem=mem)
# At this point an I2C controller can read and write `mem`.
...
# Deinitialise the I2C target.
i2c.deinit()
Note that some ports require an ``id``, and maybe ``scl`` and ``sda`` pins, to be
passed to the `I2CTarget` constructor, to select the hardware I2C instance and
pins that it connects to.
When configured as a memory device, it's also possible to register to receive events.
For example to be notified when the memory is read/written::
from machine import I2CTarget
# Define an IRQ handler, for I2C events.
def irq_handler(i2c_target):
flags = i2c_target.irq().flags()
if flags & I2CTarget.IRQ_END_READ:
print("controller read target at addr", i2c_target.memaddr)
if flags & I2CTarget.IRQ_END_WRITE:
print("controller wrote target at addr", i2c_target.memaddr)
# Create the I2C target and register to receive default events.
mem = bytearray(8)
i2c = I2CTarget(addr=67, mem=mem)
i2c.irq(irq_handler)
More complicated I2C devices can be implemented using the full set of events. For
example, to see the raw events as they are triggered::
from machine import I2CTarget
# Define an IRQ handler that prints the event id and responds to reads/writes.
def irq_handler(i2c_target, buf=bytearray(1)):
flags = i2c_target.irq().flags()
print(flags)
if flags & I2CTarget.IRQ_READ_REQ:
i2c_target.write(buf)
if flags & I2CTarget.IRQ_WRITE_REQ:
i2c_target.readinto(buf)
# Create the I2C target and register to receive all events.
i2c = I2CTarget(addr=67)
all_triggers = (
I2CTarget.IRQ_ADDR_MATCH_READ
| I2CTarget.IRQ_ADDR_MATCH_WRITE
| I2CTarget.IRQ_READ_REQ
| I2CTarget.IRQ_WRITE_REQ
| I2CTarget.IRQ_END_READ
| I2CTarget.IRQ_END_WRITE
)
i2c.irq(irq_handler, trigger=all_triggers, hard=True)
Constructors
------------
.. class:: I2CTarget(id, addr, *, addrsize=7, mem=None, mem_addrsize=8, scl=None, sda=None)
Construct and return a new I2CTarget object using the following parameters:
- *id* identifies a particular I2C peripheral. Allowed values depend on the
particular port/board. Some ports have a default in which case this parameter
can be omitted.
- *addr* is the I2C address of the target.
- *addrsize* is the number of bits in the I2C target address. Valid values
are 7 and 10.
- *mem* is an object with the buffer protocol that is writable. If not
specified then there is no backing memory and data must be read/written
using the :meth:`I2CTarget.readinto` and :meth:`I2CTarget.write` methods.
- *mem_addrsize* is the number of bits in the memory address. Valid values
are 0, 8, 16, 24 and 32.
- *scl* is a pin object specifying the pin to use for SCL.
- *sda* is a pin object specifying the pin to use for SDA.
Note that some ports/boards will have default values of *scl* and *sda*
that can be changed in this constructor. Others will have fixed values
of *scl* and *sda* that cannot be changed.
General Methods
---------------
.. method:: I2CTarget.deinit()
Deinitialise the I2C target. After this method is called the hardware will no
longer respond to requests on the I2C bus, and no other methods can be called.
.. method:: I2CTarget.readinto(buf)
Read into the given buffer any pending bytes written by the I2C controller.
Returns the number of bytes read.
.. method:: I2CTarget.write(buf)
Write out the bytes from the given buffer, to be passed to the I2C controller
after it sends a read request. Returns the number of bytes written. Most ports
only accept one byte at a time to this method.
.. method:: I2CTarget.irq(handler=None, trigger=IRQ_END_READ|IRQ_END_WRITE, hard=False)
Configure an IRQ *handler* to be called when an event occurs. The possible events are
given by the following constants, which can be or'd together and passed to the *trigger*
argument:
- ``IRQ_ADDR_MATCH_READ`` indicates that the target was addressed by a
controller for a read transaction.
- ``IRQ_ADDR_MATCH_READ`` indicates that the target was addressed by a
controller for a write transaction.
- ``IRQ_READ_REQ`` indicates that the controller is requesting data, and this
request must be satisfied by calling `I2CTarget.write` with the data to be
passed back to the controller.
- ``IRQ_WRITE_REQ`` indicates that the controller has written data, and the
data must be read by calling `I2CTarget.readinto`.
- ``IRQ_END_READ`` indicates that the controller has finished a read transaction.
- ``IRQ_END_WRITE`` indicates that the controller has finished a write transaction.
Not all triggers are available on all ports. If a port has the constant then that
event is available.
Note the following restrictions:
- ``IRQ_ADDR_MATCH_READ``, ``IRQ_ADDR_MATCH_READ``, ``IRQ_READ_REQ`` and
``IRQ_WRITE_REQ`` must be handled by a hard IRQ callback (with the *hard* argument
set to ``True``). This is because these events have very strict timing requirements
and must usually be satisfied synchronously with the hardware event.
- ``IRQ_END_READ`` and ``IRQ_END_WRITE`` may be handled by either a soft or hard
IRQ callback (although note that all events must be registered with the same handler,
so if any events need a hard callback then all events must be hard).
- If a memory buffer has been supplied in the constructor then ``IRQ_END_WRITE``
is not emitted for the transaction that writes the memory address. This is to
allow ``IRQ_END_READ`` and ``IRQ_END_WRITE`` to function correctly as soft IRQ
callbacks, where the IRQ handler may be called quite some time after the actual
hardware event.
.. attribute:: I2CTarget.memaddr
The integer value of the most recent memory address that was selected by the I2C
controller (only valid if ``mem`` was specified in the constructor).
Constants
---------
.. data:: I2CTarget.IRQ_ADDR_MATCH_READ
I2CTarget.IRQ_ADDR_MATCH_WRITE
I2CTarget.IRQ_READ_REQ
I2CTarget.IRQ_WRITE_REQ
I2CTarget.IRQ_END_READ
I2CTarget.IRQ_END_WRITE
IRQ trigger sources.
|
