Debian Codegraph @

libraries/Wire/src/utility/twi.c

raw
1 /*
2 twi.c - TWI/I2C library for Wiring & Arduino
3 Copyright (c) 2006 Nicholas Zambetti. All right reserved.
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18
19 Modified 2012 by Todd Krein ([email protected]) to implement repeated starts
20 Modified 2020 by Greyson Christoforo ([email protected]) to implement timeouts
21 */
22
23 #include <math.h>
24 #include <stdlib.h>
25 #include <inttypes.h>
26 #include <avr/io.h>
27 #include <avr/interrupt.h>
28 #include <util/delay.h>
29 #include <compat/twi.h>
30 #include "Arduino.h" // for digitalWrite and micros
31
32 #ifndef cbi
33 #define cbi(sfr, bit) (_SFR_BYTE(sfr) &= ~_BV(bit))
34 #endif
35
36 #ifndef sbi
37 #define sbi(sfr, bit) (_SFR_BYTE(sfr) |= _BV(bit))
38 #endif
39
40 #include "pins_arduino.h"
41 #include "twi.h"
42
43 static volatile uint8_t twi_state;
44 static volatile uint8_t twi_slarw;
45 static volatile uint8_t twi_sendStop; // should the transaction end with a stop
46 static volatile uint8_t twi_inRepStart; // in the middle of a repeated start
47
48 // twi_timeout_us > 0 prevents the code from getting stuck in various while loops here
49 // if twi_timeout_us == 0 then timeout checking is disabled (the previous Wire lib behavior)
50 // at some point in the future, the default twi_timeout_us value could become 25000
51 // and twi_do_reset_on_timeout could become true
52 // to conform to the SMBus standard
53 // http://smbus.org/specs/SMBus_3_1_20180319.pdf
54 static volatile uint32_t twi_timeout_us = 0ul;
55 static volatile bool twi_timed_out_flag = false; // a timeout has been seen
56 static volatile bool twi_do_reset_on_timeout = false; // reset the TWI registers on timeout
57
58 static void (*twi_onSlaveTransmit)(void);
59 static void (*twi_onSlaveReceive)(uint8_t*, int);
60
61 static uint8_t twi_masterBuffer[TWI_BUFFER_LENGTH];
62 static volatile uint8_t twi_masterBufferIndex;
63 static volatile uint8_t twi_masterBufferLength;
64
65 static uint8_t twi_txBuffer[TWI_BUFFER_LENGTH];
66 static volatile uint8_t twi_txBufferIndex;
67 static volatile uint8_t twi_txBufferLength;
68
69 static uint8_t twi_rxBuffer[TWI_BUFFER_LENGTH];
70 static volatile uint8_t twi_rxBufferIndex;
71
72 static volatile uint8_t twi_error;
73
74 /*
75 * Function twi_init
76 * Desc readys twi pins and sets twi bitrate
77 * Input none
78 * Output none
79 */
80 void twi_init(void)
81 {
82 // initialize state
83 twi_state = TWI_READY;
84 twi_sendStop = true; // default value
85 twi_inRepStart = false;
86
87 // activate internal pullups for twi.
88 digitalWrite(SDA, 1);
89 digitalWrite(SCL, 1);
90
91 // initialize twi prescaler and bit rate
92 cbi(TWSR, TWPS0);
93 cbi(TWSR, TWPS1);
94 TWBR = ((F_CPU / TWI_FREQ) - 16) / 2;
95
96 /* twi bit rate formula from atmega128 manual pg 204
97 SCL Frequency = CPU Clock Frequency / (16 + (2 * TWBR))
98 note: TWBR should be 10 or higher for master mode
99 It is 72 for a 16mhz Wiring board with 100kHz TWI */
100
101 // enable twi module, acks, and twi interrupt
102 TWCR = _BV(TWEN) | _BV(TWIE) | _BV(TWEA);
103 }
104
105 /*
106 * Function twi_disable
107 * Desc disables twi pins
108 * Input none
109 * Output none
110 */
111 void twi_disable(void)
112 {
113 // disable twi module, acks, and twi interrupt
114 TWCR &= ~(_BV(TWEN) | _BV(TWIE) | _BV(TWEA));
115
116 // deactivate internal pullups for twi.
117 digitalWrite(SDA, 0);
118 digitalWrite(SCL, 0);
119 }
120
121 /*
122 * Function twi_slaveInit
123 * Desc sets slave address and enables interrupt
124 * Input none
125 * Output none
126 */
127 void twi_setAddress(uint8_t address)
128 {
129 // set twi slave address (skip over TWGCE bit)
130 TWAR = address << 1;
131 }
132
133 /*
134 * Function twi_setClock
135 * Desc sets twi bit rate
136 * Input Clock Frequency
137 * Output none
138 */
139 void twi_setFrequency(uint32_t frequency)
140 {
141 TWBR = ((F_CPU / frequency) - 16) / 2;
142
143 /* twi bit rate formula from atmega128 manual pg 204
144 SCL Frequency = CPU Clock Frequency / (16 + (2 * TWBR))
145 note: TWBR should be 10 or higher for master mode
146 It is 72 for a 16mhz Wiring board with 100kHz TWI */
147 }
148
149 /*
150 * Function twi_readFrom
151 * Desc attempts to become twi bus master and read a
152 * series of bytes from a device on the bus
153 * Input address: 7bit i2c device address
154 * data: pointer to byte array
155 * length: number of bytes to read into array
156 * sendStop: Boolean indicating whether to send a stop at the end
157 * Output number of bytes read
158 */
159 uint8_t twi_readFrom(uint8_t address, uint8_t* data, uint8_t length, uint8_t sendStop)
160 {
161 uint8_t i;
162
163 // ensure data will fit into buffer
164 if(TWI_BUFFER_LENGTH < length){
165 return 0;
166 }
167
168 // wait until twi is ready, become master receiver
169 uint32_t startMicros = micros();
170 while(TWI_READY != twi_state){
171 if((twi_timeout_us > 0ul) && ((micros() - startMicros) > twi_timeout_us)) {
172 twi_handleTimeout(twi_do_reset_on_timeout);
173 return 0;
174 }
175 }
176 twi_state = TWI_MRX;
177 twi_sendStop = sendStop;
178 // reset error state (0xFF.. no error occurred)
179 twi_error = 0xFF;
180
181 // initialize buffer iteration vars
182 twi_masterBufferIndex = 0;
183 twi_masterBufferLength = length-1; // This is not intuitive, read on...
184 // On receive, the previously configured ACK/NACK setting is transmitted in
185 // response to the received byte before the interrupt is signalled.
186 // Therefore we must actually set NACK when the _next_ to last byte is
187 // received, causing that NACK to be sent in response to receiving the last
188 // expected byte of data.
189
190 // build sla+w, slave device address + w bit
191 twi_slarw = TW_READ;
192 twi_slarw |= address << 1;
193
194 if (true == twi_inRepStart) {
195 // if we're in the repeated start state, then we've already sent the start,
196 // (@@@ we hope), and the TWI statemachine is just waiting for the address byte.
197 // We need to remove ourselves from the repeated start state before we enable interrupts,
198 // since the ISR is ASYNC, and we could get confused if we hit the ISR before cleaning
199 // up. Also, don't enable the START interrupt. There may be one pending from the
200 // repeated start that we sent ourselves, and that would really confuse things.
201 twi_inRepStart = false; // remember, we're dealing with an ASYNC ISR
202 startMicros = micros();
203 do {
204 TWDR = twi_slarw;
205 if((twi_timeout_us > 0ul) && ((micros() - startMicros) > twi_timeout_us)) {
206 twi_handleTimeout(twi_do_reset_on_timeout);
207 return 0;
208 }
209 } while(TWCR & _BV(TWWC));
210 TWCR = _BV(TWINT) | _BV(TWEA) | _BV(TWEN) | _BV(TWIE); // enable INTs, but not START
211 } else {
212 // send start condition
213 TWCR = _BV(TWEN) | _BV(TWIE) | _BV(TWEA) | _BV(TWINT) | _BV(TWSTA);
214 }
215
216 // wait for read operation to complete
217 startMicros = micros();
218 while(TWI_MRX == twi_state){
219 if((twi_timeout_us > 0ul) && ((micros() - startMicros) > twi_timeout_us)) {
220 twi_handleTimeout(twi_do_reset_on_timeout);
221 return 0;
222 }
223 }
224
225 if (twi_masterBufferIndex < length) {
226 length = twi_masterBufferIndex;
227 }
228
229 // copy twi buffer to data
230 for(i = 0; i < length; ++i){
231 data[i] = twi_masterBuffer[i];
232 }
233
234 return length;
235 }
236
237 /*
238 * Function twi_writeTo
239 * Desc attempts to become twi bus master and write a
240 * series of bytes to a device on the bus
241 * Input address: 7bit i2c device address
242 * data: pointer to byte array
243 * length: number of bytes in array
244 * wait: boolean indicating to wait for write or not
245 * sendStop: boolean indicating whether or not to send a stop at the end
246 * Output 0 .. success
247 * 1 .. length to long for buffer
248 * 2 .. address send, NACK received
249 * 3 .. data send, NACK received
250 * 4 .. other twi error (lost bus arbitration, bus error, ..)
251 * 5 .. timeout
252 */
253 uint8_t twi_writeTo(uint8_t address, uint8_t* data, uint8_t length, uint8_t wait, uint8_t sendStop)
254 {
255 uint8_t i;
256
257 // ensure data will fit into buffer
258 if(TWI_BUFFER_LENGTH < length){
259 return 1;
260 }
261
262 // wait until twi is ready, become master transmitter
263 uint32_t startMicros = micros();
264 while(TWI_READY != twi_state){
265 if((twi_timeout_us > 0ul) && ((micros() - startMicros) > twi_timeout_us)) {
266 twi_handleTimeout(twi_do_reset_on_timeout);
267 return (5);
268 }
269 }
270 twi_state = TWI_MTX;
271 twi_sendStop = sendStop;
272 // reset error state (0xFF.. no error occurred)
273 twi_error = 0xFF;
274
275 // initialize buffer iteration vars
276 twi_masterBufferIndex = 0;
277 twi_masterBufferLength = length;
278
279 // copy data to twi buffer
280 for(i = 0; i < length; ++i){
281 twi_masterBuffer[i] = data[i];
282 }
283
284 // build sla+w, slave device address + w bit
285 twi_slarw = TW_WRITE;
286 twi_slarw |= address << 1;
287
288 // if we're in a repeated start, then we've already sent the START
289 // in the ISR. Don't do it again.
290 //
291 if (true == twi_inRepStart) {
292 // if we're in the repeated start state, then we've already sent the start,
293 // (@@@ we hope), and the TWI statemachine is just waiting for the address byte.
294 // We need to remove ourselves from the repeated start state before we enable interrupts,
295 // since the ISR is ASYNC, and we could get confused if we hit the ISR before cleaning
296 // up. Also, don't enable the START interrupt. There may be one pending from the
297 // repeated start that we sent ourselves, and that would really confuse things.
298 twi_inRepStart = false; // remember, we're dealing with an ASYNC ISR
299 startMicros = micros();
300 do {
301 TWDR = twi_slarw;
302 if((twi_timeout_us > 0ul) && ((micros() - startMicros) > twi_timeout_us)) {
303 twi_handleTimeout(twi_do_reset_on_timeout);
304 return (5);
305 }
306 } while(TWCR & _BV(TWWC));
307 TWCR = _BV(TWINT) | _BV(TWEA) | _BV(TWEN) | _BV(TWIE); // enable INTs, but not START
308 } else {
309 // send start condition
310 TWCR = _BV(TWINT) | _BV(TWEA) | _BV(TWEN) | _BV(TWIE) | _BV(TWSTA); // enable INTs
311 }
312
313 // wait for write operation to complete
314 startMicros = micros();
315 while(wait && (TWI_MTX == twi_state)){
316 if((twi_timeout_us > 0ul) && ((micros() - startMicros) > twi_timeout_us)) {
317 twi_handleTimeout(twi_do_reset_on_timeout);
318 return (5);
319 }
320 }
321
322 if (twi_error == 0xFF)
323 return 0; // success
324 else if (twi_error == TW_MT_SLA_NACK)
325 return 2; // error: address send, nack received
326 else if (twi_error == TW_MT_DATA_NACK)
327 return 3; // error: data send, nack received
328 else
329 return 4; // other twi error
330 }
331
332 /*
333 * Function twi_transmit
334 * Desc fills slave tx buffer with data
335 * must be called in slave tx event callback
336 * Input data: pointer to byte array
337 * length: number of bytes in array
338 * Output 1 length too long for buffer
339 * 2 not slave transmitter
340 * 0 ok
341 */
342 uint8_t twi_transmit(const uint8_t* data, uint8_t length)
343 {
344 uint8_t i;
345
346 // ensure data will fit into buffer
347 if(TWI_BUFFER_LENGTH < (twi_txBufferLength+length)){
348 return 1;
349 }
350
351 // ensure we are currently a slave transmitter
352 if(TWI_STX != twi_state){
353 return 2;
354 }
355
356 // set length and copy data into tx buffer
357 for(i = 0; i < length; ++i){
358 twi_txBuffer[twi_txBufferLength+i] = data[i];
359 }
360 twi_txBufferLength += length;
361
362 return 0;
363 }
364
365 /*
366 * Function twi_attachSlaveRxEvent
367 * Desc sets function called before a slave read operation
368 * Input function: callback function to use
369 * Output none
370 */
371 void twi_attachSlaveRxEvent( void (*function)(uint8_t*, int) )
372 {
373 twi_onSlaveReceive = function;
374 }
375
376 /*
377 * Function twi_attachSlaveTxEvent
378 * Desc sets function called before a slave write operation
379 * Input function: callback function to use
380 * Output none
381 */
382 void twi_attachSlaveTxEvent( void (*function)(void) )
383 {
384 twi_onSlaveTransmit = function;
385 }
386
387 /*
388 * Function twi_reply
389 * Desc sends byte or readys receive line
390 * Input ack: byte indicating to ack or to nack
391 * Output none
392 */
393 void twi_reply(uint8_t ack)
394 {
395 // transmit master read ready signal, with or without ack
396 if(ack){
397 TWCR = _BV(TWEN) | _BV(TWIE) | _BV(TWINT) | _BV(TWEA);
398 }else{
399 TWCR = _BV(TWEN) | _BV(TWIE) | _BV(TWINT);
400 }
401 }
402
403 /*
404 * Function twi_stop
405 * Desc relinquishes bus master status
406 * Input none
407 * Output none
408 */
409 void twi_stop(void)
410 {
411 // send stop condition
412 TWCR = _BV(TWEN) | _BV(TWIE) | _BV(TWEA) | _BV(TWINT) | _BV(TWSTO);
413
414 // wait for stop condition to be executed on bus
415 // TWINT is not set after a stop condition!
416 // We cannot use micros() from an ISR, so approximate the timeout with cycle-counted delays
417 const uint8_t us_per_loop = 8;
418 uint32_t counter = (twi_timeout_us + us_per_loop - 1)/us_per_loop; // Round up
419 while(TWCR & _BV(TWSTO)){
420 if(twi_timeout_us > 0ul){
421 if (counter > 0ul){
422 _delay_us(us_per_loop);
423 counter--;
424 } else {
425 twi_handleTimeout(twi_do_reset_on_timeout);
426 return;
427 }
428 }
429 }
430
431 // update twi state
432 twi_state = TWI_READY;
433 }
434
435 /*
436 * Function twi_releaseBus
437 * Desc releases bus control
438 * Input none
439 * Output none
440 */
441 void twi_releaseBus(void)
442 {
443 // release bus
444 TWCR = _BV(TWEN) | _BV(TWIE) | _BV(TWEA) | _BV(TWINT);
445
446 // update twi state
447 twi_state = TWI_READY;
448 }
449
450 /*
451 * Function twi_setTimeoutInMicros
452 * Desc set a timeout for while loops that twi might get stuck in
453 * Input timeout value in microseconds (0 means never time out)
454 * Input reset_with_timeout: true causes timeout events to reset twi
455 * Output none
456 */
457 void twi_setTimeoutInMicros(uint32_t timeout, bool reset_with_timeout){
458 twi_timed_out_flag = false;
459 twi_timeout_us = timeout;
460 twi_do_reset_on_timeout = reset_with_timeout;
461 }
462
463 /*
464 * Function twi_handleTimeout
465 * Desc this gets called whenever a while loop here has lasted longer than
466 * twi_timeout_us microseconds. always sets twi_timed_out_flag
467 * Input reset: true causes this function to reset the twi hardware interface
468 * Output none
469 */
470 void twi_handleTimeout(bool reset){
471 twi_timed_out_flag = true;
472
473 if (reset) {
474 // remember bitrate and address settings
475 uint8_t previous_TWBR = TWBR;
476 uint8_t previous_TWAR = TWAR;
477
478 // reset the interface
479 twi_disable();
480 twi_init();
481
482 // reapply the previous register values
483 TWAR = previous_TWAR;
484 TWBR = previous_TWBR;
485 }
486 }
487
488 /*
489 * Function twi_manageTimeoutFlag
490 * Desc returns true if twi has seen a timeout
491 * optionally clears the timeout flag
492 * Input clear_flag: true if we should reset the hardware
493 * Output the value of twi_timed_out_flag when the function was called
494 */
495 bool twi_manageTimeoutFlag(bool clear_flag){
496 bool flag = twi_timed_out_flag;
497 if (clear_flag){
498 twi_timed_out_flag = false;
499 }
500 return(flag);
501 }
502
503 ISR(TWI_vect)
504 {
505 switch(TW_STATUS){
506 // All Master
507 case TW_START: // sent start condition
508 case TW_REP_START: // sent repeated start condition
509 // copy device address and r/w bit to output register and ack
510 TWDR = twi_slarw;
511 twi_reply(1);
512 break;
513
514 // Master Transmitter
515 case TW_MT_SLA_ACK: // slave receiver acked address
516 case TW_MT_DATA_ACK: // slave receiver acked data
517 // if there is data to send, send it, otherwise stop
518 if(twi_masterBufferIndex < twi_masterBufferLength){
519 // copy data to output register and ack
520 TWDR = twi_masterBuffer[twi_masterBufferIndex++];
521 twi_reply(1);
522 }else{
523 if (twi_sendStop){
524 twi_stop();
525 } else {
526 twi_inRepStart = true; // we're gonna send the START
527 // don't enable the interrupt. We'll generate the start, but we
528 // avoid handling the interrupt until we're in the next transaction,
529 // at the point where we would normally issue the start.
530 TWCR = _BV(TWINT) | _BV(TWSTA)| _BV(TWEN) ;
531 twi_state = TWI_READY;
532 }
533 }
534 break;
535 case TW_MT_SLA_NACK: // address sent, nack received
536 twi_error = TW_MT_SLA_NACK;
537 twi_stop();
538 break;
539 case TW_MT_DATA_NACK: // data sent, nack received
540 twi_error = TW_MT_DATA_NACK;
541 twi_stop();
542 break;
543 case TW_MT_ARB_LOST: // lost bus arbitration
544 twi_error = TW_MT_ARB_LOST;
545 twi_releaseBus();
546 break;
547
548 // Master Receiver
549 case TW_MR_DATA_ACK: // data received, ack sent
550 // put byte into buffer
551 twi_masterBuffer[twi_masterBufferIndex++] = TWDR;
552 __attribute__ ((fallthrough));
553 case TW_MR_SLA_ACK: // address sent, ack received
554 // ack if more bytes are expected, otherwise nack
555 if(twi_masterBufferIndex < twi_masterBufferLength){
556 twi_reply(1);
557 }else{
558 twi_reply(0);
559 }
560 break;
561 case TW_MR_DATA_NACK: // data received, nack sent
562 // put final byte into buffer
563 twi_masterBuffer[twi_masterBufferIndex++] = TWDR;
564 if (twi_sendStop){
565 twi_stop();
566 } else {
567 twi_inRepStart = true; // we're gonna send the START
568 // don't enable the interrupt. We'll generate the start, but we
569 // avoid handling the interrupt until we're in the next transaction,
570 // at the point where we would normally issue the start.
571 TWCR = _BV(TWINT) | _BV(TWSTA)| _BV(TWEN) ;
572 twi_state = TWI_READY;
573 }
574 break;
575 case TW_MR_SLA_NACK: // address sent, nack received
576 twi_stop();
577 break;
578 // TW_MR_ARB_LOST handled by TW_MT_ARB_LOST case
579
580 // Slave Receiver
581 case TW_SR_SLA_ACK: // addressed, returned ack
582 case TW_SR_GCALL_ACK: // addressed generally, returned ack
583 case TW_SR_ARB_LOST_SLA_ACK: // lost arbitration, returned ack
584 case TW_SR_ARB_LOST_GCALL_ACK: // lost arbitration, returned ack
585 // enter slave receiver mode
586 twi_state = TWI_SRX;
587 // indicate that rx buffer can be overwritten and ack
588 twi_rxBufferIndex = 0;
589 twi_reply(1);
590 break;
591 case TW_SR_DATA_ACK: // data received, returned ack
592 case TW_SR_GCALL_DATA_ACK: // data received generally, returned ack
593 // if there is still room in the rx buffer
594 if(twi_rxBufferIndex < TWI_BUFFER_LENGTH){
595 // put byte in buffer and ack
596 twi_rxBuffer[twi_rxBufferIndex++] = TWDR;
597 twi_reply(1);
598 }else{
599 // otherwise nack
600 twi_reply(0);
601 }
602 break;
603 case TW_SR_STOP: // stop or repeated start condition received
604 // ack future responses and leave slave receiver state
605 twi_releaseBus();
606 // put a null char after data if there's room
607 if(twi_rxBufferIndex < TWI_BUFFER_LENGTH){
608 twi_rxBuffer[twi_rxBufferIndex] = '\0';
609 }
610 // callback to user defined callback
611 twi_onSlaveReceive(twi_rxBuffer, twi_rxBufferIndex);
612 // since we submit rx buffer to "wire" library, we can reset it
613 twi_rxBufferIndex = 0;
614 break;
615 case TW_SR_DATA_NACK: // data received, returned nack
616 case TW_SR_GCALL_DATA_NACK: // data received generally, returned nack
617 // nack back at master
618 twi_reply(0);
619 break;
620
621 // Slave Transmitter
622 case TW_ST_SLA_ACK: // addressed, returned ack
623 case TW_ST_ARB_LOST_SLA_ACK: // arbitration lost, returned ack
624 // enter slave transmitter mode
625 twi_state = TWI_STX;
626 // ready the tx buffer index for iteration
627 twi_txBufferIndex = 0;
628 // set tx buffer length to be zero, to verify if user changes it
629 twi_txBufferLength = 0;
630 // request for txBuffer to be filled and length to be set
631 // note: user must call twi_transmit(bytes, length) to do this
632 twi_onSlaveTransmit();
633 // if they didn't change buffer & length, initialize it
634 if(0 == twi_txBufferLength){
635 twi_txBufferLength = 1;
636 twi_txBuffer[0] = 0x00;
637 }
638 __attribute__ ((fallthrough));
639 // transmit first byte from buffer, fall
640 case TW_ST_DATA_ACK: // byte sent, ack returned
641 // copy data to output register
642 TWDR = twi_txBuffer[twi_txBufferIndex++];
643 // if there is more to send, ack, otherwise nack
644 if(twi_txBufferIndex < twi_txBufferLength){
645 twi_reply(1);
646 }else{
647 twi_reply(0);
648 }
649 break;
650 case TW_ST_DATA_NACK: // received nack, we are done
651 case TW_ST_LAST_DATA: // received ack, but we are done already!
652 // ack future responses
653 twi_reply(1);
654 // leave slave receiver state
655 twi_state = TWI_READY;
656 break;
657
658 // All
659 case TW_NO_INFO: // no state information
660 break;
661 case TW_BUS_ERROR: // bus error, illegal stop/start
662 twi_error = TW_BUS_ERROR;
663 twi_stop();
664 break;
665 }
666 }