| 1 | # You may distribute under the terms of either the GNU General Public License | ||||||||||||||
| 2 | # or the Artistic License (the same terms as Perl itself) | ||||||||||||||
| 3 | # | ||||||||||||||
| 4 | # (C) Paul Evans, 2015-2023 -- leonerd@leonerd.org.uk | ||||||||||||||
| 5 | |||||||||||||||
| 6 | 6 | ▶ | use v5.26; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 7 | 6 | ▶ | use warnings; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 8 | 6 | ▶ | use Object::Pad 0.800; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 9 | |||||||||||||||
| 10 | package Device::Chip::MCP23x17 0.07; | ||||||||||||||
| 11 | class Device::Chip::MCP23x17 | ||||||||||||||
| 12 | 1 | ▶ | :isa(Device::Chip); | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 13 | |||||||||||||||
| 14 | 6 | ▶ | use Future::AsyncAwait; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 15 | |||||||||||||||
| 16 | =head1 NAME | ||||||||||||||
| 17 | |||||||||||||||
| 18 | C<Device::Chip::MCP23x17> - chip driver for the F<MCP23x17> family | ||||||||||||||
| 19 | |||||||||||||||
| 20 | =head1 SYNOPSIS | ||||||||||||||
| 21 | |||||||||||||||
| 22 | use Device::Chip::MCP23S17; | ||||||||||||||
| 23 | use Future::AsyncAwait; | ||||||||||||||
| 24 | |||||||||||||||
| 25 | use constant { HIGH => 0xFFFF, LOW => 0 }; | ||||||||||||||
| 26 | |||||||||||||||
| 27 | my $chip = Device::Chip::MCP23S17->new; | ||||||||||||||
| 28 | await $chip->mount( Device::Chip::Adapter::...->new ); | ||||||||||||||
| 29 | |||||||||||||||
| 30 | foreach my $bit ( 0 .. 15 ) { | ||||||||||||||
| 31 | await $chip->write_gpio( HIGH, 1 << $bit ); | ||||||||||||||
| 32 | sleep 1; | ||||||||||||||
| 33 | await $chip->write_gpio( LOW, 1 << $bit ); | ||||||||||||||
| 34 | } | ||||||||||||||
| 35 | |||||||||||||||
| 36 | =head1 DESCRIPTION | ||||||||||||||
| 37 | |||||||||||||||
| 38 | This L<Device::Chip> subclass provides specific communication to the | ||||||||||||||
| 39 | F<Microchip> F<MCP23x17> family of chips. | ||||||||||||||
| 40 | |||||||||||||||
| 41 | This module itself is an abstract base; to talk to a specific chip see | ||||||||||||||
| 42 | one of the following subclasses: | ||||||||||||||
| 43 | |||||||||||||||
| 44 | =over 4 | ||||||||||||||
| 45 | |||||||||||||||
| 46 | F<MCP23S17> over SPI - see L<Device::Chip::MCP23S17> | ||||||||||||||
| 47 | |||||||||||||||
| 48 | =back | ||||||||||||||
| 49 | |||||||||||||||
| 50 | Aside from the method of communication with the actual chip hardware, these | ||||||||||||||
| 51 | modules all provide the same higher-level API to the containing application. | ||||||||||||||
| 52 | |||||||||||||||
| 53 | This module currently only supports a chip running in the C<IOCON.BANK=0> | ||||||||||||||
| 54 | configuration. | ||||||||||||||
| 55 | |||||||||||||||
| 56 | =cut | ||||||||||||||
| 57 | |||||||||||||||
| 58 | ADJUST | ||||||||||||||
| 59 | { | ||||||||||||||
| 60 | $self->reset; | ||||||||||||||
| 61 | } | ||||||||||||||
| 62 | |||||||||||||||
| 63 | 6 | =head1 MOUNT PARAMETERS | |||||||||||||
| 64 | |||||||||||||||
| 65 | =head2 reset | ||||||||||||||
| 66 | |||||||||||||||
| 67 | The name of the GPIO line on the adapter that is connected to the C<RESET#> | ||||||||||||||
| 68 | pin of the chip, if there is one. This will be used by the L</reset> method. | ||||||||||||||
| 69 | |||||||||||||||
| 70 | =cut | ||||||||||||||
| 71 | |||||||||||||||
| 72 | 6 | field $_resetpin; | |||||||||||||
| 73 | |||||||||||||||
| 74 | 5 | ▶ | async method mount ( $adapter, %params ) | ||||||||||||
|
Subroutine
mount: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||
| 75 | 5 | { | |||||||||||||
| 76 | 5 | $_resetpin = delete $params{reset}; | |||||||||||||
| 77 | |||||||||||||||
| 78 | 5 | return await $self->SUPER::mount( $adapter, %params ); | |||||||||||||
| 79 | 6 | } | |||||||||||||
| 80 | |||||||||||||||
| 81 | 6 | ▶ | use constant { | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 82 | # Register allocations when in IOCON.BANK=0 mode | ||||||||||||||
| 83 | # TODO: we don't yet support BANK=1 mode | ||||||||||||||
| 84 | 6 | REG_IODIR => 0x00, | |||||||||||||
| 85 | REG_IPOL => 0x02, | ||||||||||||||
| 86 | REG_GPINTEN => 0x04, | ||||||||||||||
| 87 | REG_DEFVAL => 0x06, | ||||||||||||||
| 88 | REG_INTCON => 0x08, | ||||||||||||||
| 89 | REG_IOCON => 0x0A, | ||||||||||||||
| 90 | REG_GPPU => 0x0C, | ||||||||||||||
| 91 | REG_INTF => 0x0E, | ||||||||||||||
| 92 | REG_INTCAP => 0x10, | ||||||||||||||
| 93 | REG_GPIO => 0x12, | ||||||||||||||
| 94 | REG_OLAT => 0x14, | ||||||||||||||
| 95 | 6 | }; | |||||||||||||
| 96 | |||||||||||||||
| 97 | 6 | field %_regcache; | |||||||||||||
| 98 | |||||||||||||||
| 99 | 17 | ▶ | async method _cached_maskedwrite_u16 ( $name, $val, $mask ) | ||||||||||||
|
Subroutine
_cached_maskedwrite_u16: called CC=4 SCAR=13.9
| |||||||||||||||
| 100 | 17 | { | |||||||||||||
| 101 | 17 | my $want = ( $_regcache{$name} & ~$mask ) | ( $val & $mask ); | |||||||||||||
| 102 | |||||||||||||||
| 103 | 17 | ▶ | return if ( my $got = $_regcache{$name} ) == $want; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 104 | 11 | $_regcache{$name} = $want; | |||||||||||||
| 105 | |||||||||||||||
| 106 | 11 | my $reg = __PACKAGE__->can( "REG_\U$name" )->(); | |||||||||||||
| 107 | |||||||||||||||
| 108 | 11 | ▶ | if( ( $got & 0xFF00 ) == ( $want & 0xFF00 ) ) { | ||||||||||||
|
Branch: 2 branches
| |||||||||||||||
| 109 | # low-byte write | ||||||||||||||
| 110 | 9 | await $self->write_reg( $reg, pack "C", $want & 0x00FF ); | |||||||||||||
| 111 | } | ||||||||||||||
| 112 | elsif( ( $got & 0x00FF ) == ( $want & 0x00FF ) ) { | ||||||||||||||
| 113 | 2 | await $self->write_reg( $reg+1, pack "C", ( $want & 0xFF00 ) >> 8 ); | |||||||||||||
| 114 | } | ||||||||||||||
| 115 | else { | ||||||||||||||
| 116 | 0 | await $self->write_reg( $reg, pack "S<", $want ); | |||||||||||||
| 117 | } | ||||||||||||||
| 118 | 6 | } | |||||||||||||
| 119 | |||||||||||||||
| 120 | =head1 METHODS | ||||||||||||||
| 121 | |||||||||||||||
| 122 | The following methods documented in an C<await> expression return L<Future> | ||||||||||||||
| 123 | instances. | ||||||||||||||
| 124 | |||||||||||||||
| 125 | Each method that takes a C<$mask> parameter uses it to select which IO pins | ||||||||||||||
| 126 | are affected. The mask is a 16-bit integer; selecting only those pins for | ||||||||||||||
| 127 | which bits are set. The lower 8 bits relate to the C<GPA> pins, the higher 8 | ||||||||||||||
| 128 | to the C<GPB> pins. Pins that are not selected by the mask remain unaffected. | ||||||||||||||
| 129 | |||||||||||||||
| 130 | =cut | ||||||||||||||
| 131 | |||||||||||||||
| 132 | =head2 reset | ||||||||||||||
| 133 | |||||||||||||||
| 134 | await $chip->reset; | ||||||||||||||
| 135 | |||||||||||||||
| 136 | Resets the cached register values back to their power-up defaults. | ||||||||||||||
| 137 | |||||||||||||||
| 138 | Additionally, if the C<reset> mount parameter is defined, pulses the C<RESET#> | ||||||||||||||
| 139 | pin of the chip. | ||||||||||||||
| 140 | |||||||||||||||
| 141 | =cut | ||||||||||||||
| 142 | |||||||||||||||
| 143 | async method reset | ||||||||||||||
| 144 | 5 | ▶ | { | ||||||||||||
|
Subroutine
reset: called CC=2 SCAR=7.5
Pod
documented
| |||||||||||||||
| 145 | # Default registers | ||||||||||||||
| 146 | 5 | $_regcache{iodir} = 0xffff; | |||||||||||||
| 147 | 5 | $_regcache{olat} = 0x0000; | |||||||||||||
| 148 | 5 | $_regcache{ipol} = 0x0000; | |||||||||||||
| 149 | 5 | $_regcache{gppu} = 0x0000; | |||||||||||||
| 150 | |||||||||||||||
| 151 | 5 | ▶ | if( defined( my $reset = $_resetpin ) ) { | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 152 | 0 | await $self->protocol->write_gpios( { $reset => 0 } ); | |||||||||||||
| 153 | 0 | await $self->protocol->write_gpios( { $reset => 1 } ); | |||||||||||||
| 154 | } | ||||||||||||||
| 155 | 6 | } | |||||||||||||
| 156 | |||||||||||||||
| 157 | =head2 write_gpio | ||||||||||||||
| 158 | |||||||||||||||
| 159 | await $chip->write_gpio( $val, $mask ); | ||||||||||||||
| 160 | |||||||||||||||
| 161 | Sets the pins named in the C<$mask> to be outputs, and sets their values from | ||||||||||||||
| 162 | the bits in C<$val>. Both values are 16-bit integers. | ||||||||||||||
| 163 | |||||||||||||||
| 164 | =cut | ||||||||||||||
| 165 | |||||||||||||||
| 166 | 6 | ▶ | async method write_gpio ( $val, $mask ) | ||||||||||||
|
Subroutine
write_gpio: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||
| 167 | 6 | { | |||||||||||||
| 168 | # Write the values before the direction, so as not to cause glitches | ||||||||||||||
| 169 | 6 | await $self->_cached_maskedwrite_u16( olat => $val, $mask ), | |||||||||||||
| 170 | await $self->_cached_maskedwrite_u16( iodir => 0x0000, $mask ), | ||||||||||||||
| 171 | 6 | } | |||||||||||||
| 172 | |||||||||||||||
| 173 | =head2 read_gpio | ||||||||||||||
| 174 | |||||||||||||||
| 175 | $val = await $chip->read_gpio( $mask ); | ||||||||||||||
| 176 | |||||||||||||||
| 177 | Sets the pins named in the C<$mask> to be inputs, and reads the current pin | ||||||||||||||
| 178 | values of them. The mask and the return value are 16-bit integers. | ||||||||||||||
| 179 | |||||||||||||||
| 180 | =cut | ||||||||||||||
| 181 | |||||||||||||||
| 182 | 2 | ▶ | async method read_gpio ( $mask ) | ||||||||||||
|
Subroutine
read_gpio: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||
| 183 | 2 | { | |||||||||||||
| 184 | 2 | await $self->tris_gpio( $mask ); | |||||||||||||
| 185 | |||||||||||||||
| 186 | 2 | my $val = unpack "S<", await $self->read_reg( REG_GPIO, 2 ); | |||||||||||||
| 187 | 2 | return $val & $mask; | |||||||||||||
| 188 | 6 | } | |||||||||||||
| 189 | |||||||||||||||
| 190 | =head2 tris_gpio | ||||||||||||||
| 191 | |||||||||||||||
| 192 | await $chip->tris_gpio( $mask ); | ||||||||||||||
| 193 | |||||||||||||||
| 194 | Sets the pins named in the C<$mask> to be inputs ("tristate"). The mask is a | ||||||||||||||
| 195 | 16-bit integer. | ||||||||||||||
| 196 | |||||||||||||||
| 197 | =cut | ||||||||||||||
| 198 | |||||||||||||||
| 199 | 3 | ▶ | async method tris_gpio ( $mask ) | ||||||||||||
|
Subroutine
tris_gpio: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||
| 200 | 3 | { | |||||||||||||
| 201 | 3 | await $self->_cached_maskedwrite_u16( iodir => 0xFFFF, $mask ); | |||||||||||||
| 202 | 6 | } | |||||||||||||
| 203 | |||||||||||||||
| 204 | =head2 set_input_polarity | ||||||||||||||
| 205 | |||||||||||||||
| 206 | await $chip->set_input_polarity( $pol, $mask ); | ||||||||||||||
| 207 | |||||||||||||||
| 208 | Sets the input polarity of the pins given by C<$mask> to be the values given | ||||||||||||||
| 209 | in C<$pol>. Pins associated with bits set in C<$pol> will read with an | ||||||||||||||
| 210 | inverted sense. Both values are 16-bit integers. | ||||||||||||||
| 211 | |||||||||||||||
| 212 | =cut | ||||||||||||||
| 213 | |||||||||||||||
| 214 | 1 | ▶ | async method set_input_polarity ( $pol, $mask ) | ||||||||||||
|
Subroutine
set_input_polarity: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||
| 215 | 1 | { | |||||||||||||
| 216 | 1 | await $self->_cached_maskedwrite_u16( ipol => $pol, $mask ); | |||||||||||||
| 217 | 6 | } | |||||||||||||
| 218 | |||||||||||||||
| 219 | =head2 set_input_pullup | ||||||||||||||
| 220 | |||||||||||||||
| 221 | await $chip->set_input_pullup( $pullup, $mask ); | ||||||||||||||
| 222 | |||||||||||||||
| 223 | Enables or disables the input pullup resistors on the pins given by C<$mask> | ||||||||||||||
| 224 | as per the values given by C<$pullup>. Both values are 16-bit integers. | ||||||||||||||
| 225 | |||||||||||||||
| 226 | =cut | ||||||||||||||
| 227 | |||||||||||||||
| 228 | 1 | ▶ | async method set_input_pullup ( $pullup, $mask ) | ||||||||||||
|
Subroutine
set_input_pullup: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||
| 229 | 1 | { | |||||||||||||
| 230 | 1 | await $self->_cached_maskedwrite_u16( gppu => $pullup, $mask ); | |||||||||||||
| 231 | 6 | } | |||||||||||||
| 232 | |||||||||||||||
| 233 | =head2 as_adapter | ||||||||||||||
| 234 | |||||||||||||||
| 235 | $adapter = $chip->as_adapter; | ||||||||||||||
| 236 | |||||||||||||||
| 237 | Returns an instance implementing the L<Device::Chip::Adapter> interface, | ||||||||||||||
| 238 | allowing access to the GPIO pins via the standard adapter API. See also | ||||||||||||||
| 239 | L<Device::Chip::MCP23x17::Adapter>. | ||||||||||||||
| 240 | |||||||||||||||
| 241 | =cut | ||||||||||||||
| 242 | |||||||||||||||
| 243 | method as_adapter | ||||||||||||||
| 244 | 1 | ▶ | { | ||||||||||||
|
Subroutine
as_adapter: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||
| 245 | 1 | require Device::Chip::MCP23x17::Adapter; | |||||||||||||
| 246 | 1 | return Device::Chip::MCP23x17::Adapter->new( chip => $self ); | |||||||||||||
| 247 | 6 | } | |||||||||||||
| 248 | |||||||||||||||
| 249 | =head1 TODO | ||||||||||||||
| 250 | |||||||||||||||
| 251 | =over 4 | ||||||||||||||
| 252 | |||||||||||||||
| 253 | =item * | ||||||||||||||
| 254 | |||||||||||||||
| 255 | Wrap the interrupt-related registers - C<GPINTEN>, C<DEFVAL>, C<INTCON>, | ||||||||||||||
| 256 | C<INTF>, C<INTCAP>. Support the interrupt-related bits in C<IOCON> - | ||||||||||||||
| 257 | C<MIRROR>, C<ODR>, C<INTPOL>. | ||||||||||||||
| 258 | |||||||||||||||
| 259 | =item * | ||||||||||||||
| 260 | |||||||||||||||
| 261 | Support the general configuration bits in the C<IOCON> register - C<DISSLW>, | ||||||||||||||
| 262 | C<HAEN>. | ||||||||||||||
| 263 | |||||||||||||||
| 264 | =item * | ||||||||||||||
| 265 | |||||||||||||||
| 266 | Consider how easy/hard or indeed how useful it might be to support | ||||||||||||||
| 267 | C<IOCON.BANK=1> configuration. | ||||||||||||||
| 268 | |||||||||||||||
| 269 | =back | ||||||||||||||
| 270 | |||||||||||||||
| 271 | =head1 AUTHOR | ||||||||||||||
| 272 | |||||||||||||||
| 273 | Paul Evans <leonerd@leonerd.org.uk> | ||||||||||||||
| 274 | |||||||||||||||
| 275 | =cut | ||||||||||||||
| 276 | |||||||||||||||
| 277 | 6 | 0x55AA; | |||||||||||||