twi.c File Reference

Source file with implementation of hardware TWI/I2C functions and macros. More...

#include "twi.h"

Include dependency graph for twi.c:

Functions
unsigned char	twi_init (void)
	Initialize the TWI (I2C) hardware interface in master mode.
void	twi_disable (void)
	Disable the TWI (I2C) interface.
unsigned char	twi_status (void)
	Retrieves the current TWI status byte.
TWI_Error	twi_start (void)
	Initiates a TWI (I2C) (repeated) start condition on the bus.
void	twi_stop (void)
	Stop the TWI (I2C) transmission by generating a stop condition.
TWI_Error	twi_address (unsigned char address, TWI_Operation operation)
	Send a TWI (I2C) slave address combined with the read/write operation bit.
TWI_Error	twi_set (unsigned char data)
	Transmit a data byte over the TWI (I2C) bus.
TWI_Error	twi_get (unsigned char *data, TWI_Acknowledge acknowledge)
	Receive a data byte from the TWI (I2C) bus.

Detailed Description

Source file with implementation of hardware TWI/I2C functions and macros.

This file contains the definitions of function implementations and macros for hardware-based TWI (I2C) communication on AVR-0/1/2-Series microcontrollers.

Author

g.raf

Date

2025-09-01

Version

1.0 Release

Copyright

Copyright (c) 2025 g.raf Released under the GPLv3 License. (see LICENSE in repository)

Note

This file is part of a larger project and subject to the license specified in the repository. For updates and the complete revision history, see the GitHub repository.

See also

https://github.com/0x007e/avr0 "AVR ATmega GitHub Repository"

Function Documentation

twi_address()

TWI_Error twi_address ( unsigned char address, TWI_Operation operation )

inline

Send a TWI (I2C) slave address combined with the read/write operation bit.

Parameters

address	7-bit slave address to be transmitted.
operation	Specifies the operation type: 0 for write, 1 for read.

Returns

Returns the status code from the twi_set function indicating the result of address transmission:

• TWI_None if the address was acknowledged by the slave.
• TWI_Ack if an acknowledgement error (NACK) occurred.
• TWI_Arbitration if arbitration was lost in multi-master mode.
• TWI_General if a general error occurred.

This inline function constructs the address byte by shifting the 7-bit slave address left by one and combining it with the least significant bit representing the operation (read/write). It then calls twi_set to transmit this address byte over the TWI bus and returns the transmission status.

twi_disable()

void twi_disable ( void )

inline

Disable the TWI (I2C) interface.

This inline function disables the hardware TWI module. This effectively releases control of the TWI lines and sets the pins to reset state. Use this function to safely deactivate the TWI bus when it is no longer needed.

twi_get()

TWI_Error twi_get	(	unsigned char *	data,
		TWI_Acknowledge	acknowledge )

Receive a data byte from the TWI (I2C) bus.

Parameters

data	Pointer to a variable where the received data byte will be stored.
acknowledge	Specifies whether the master should send an ACK or NACK after receiving the byte: TWI_ACK to acknowledge receipt and request more data. TWI_NACK to signal no more data is requested.

Returns

Returns one of the following status codes:

• TWI_None: Data was successfully received and the expected ACK/NACK was sent.
• TWI_Ack: Wrong or unexpected ACK/NACK parameter or status received.
• TWI_Arbitration: Arbitration was lost in multi-master mode.
• TWI_General: A general error occurred during transmission.

This function configures the TWI hardware to receive a byte from the bus and decides whether to send an ACK or NACK based on the acknowledge parameter.

Note

The function waits until the reception is complete by polling the TWI status function for completion. The received data is then read from the MDATA register and stored at the provided pointer.

Depending on the acknowledge mode, the function sets the MCTRLB register to either send an ACK and prepare for more data reception or send a NACK and stop the communication.

Finally, the function returns the status code from the reception process.

twi_init()

unsigned char twi_init

(

void

)

Initialize the TWI (I2C) hardware interface in master mode.

Returns

Returns the current TWI status byte after initialization.

This function configures the TWI hardware registers to initialize the bus exclusively in master mode.

It sets the bitrate and activates the TWI controller using the predefined macros.

Note

If interrupt processing is enabled (TWI_TWIE), relevant interrupts are configured.

The function returns the initial TWI status for further status checking after initialization.

Here is the call graph for this function:

twi_set()

TWI_Error twi_set

(

unsigned char

data

)

Transmit a data byte over the TWI (I2C) bus.

Parameters

data	The data byte to be transmitted to the bus.

Returns

Returns one of the following status codes:

• TWI_None: Data was transmitted successfully and acknowledged by the slave.
• TWI_Ack: Acknowledgement error occurred (NACK received).
• TWI_Arbitration: Arbitration lost in multi-master mode.
• TWI_General: A general error occurred during transmission.

This function writes the provided data byte into the TWI data register. It then waits for the transmission to complete by repeatedly checking the TWI status.

The function returns the final TWI status code indicating the result of the transmission.

twi_start()

TWI_Error twi_start ( void )

inline

Initiates a TWI (I2C) (repeated) start condition on the bus.

Deprecated

This function is obsolete on newer AVR microcontrollers and is retained only for backward compatibility.

It does not perform any operation.

Returns

Always returns TWI_None as the function is effectively a no-op.

On modern AVR hardware, start conditions are managed internally by the TWI module, so this function is no longer necessary and does not initiate any bus activity.

twi_status()

unsigned char twi_status ( void )

inline

Retrieves the current TWI status byte.

Reads and returns the TWI status byte from the TWSR register, including the write collision flag.

• Bits 7 to 3 (masked with 0xF8) contain the TWI status code which indicates the current state of the TWI hardware (see TWI_STATUS_* defines).
• Bit 2 indicates a write collision error.

Returns

A byte where:

• Bits [7:3] represent the TWI status code.
• Bit [2] indicates a write collision (1 if collision occurred, 0 otherwise).

twi_stop()

void twi_stop

(

void

)

Stop the TWI (I2C) transmission by generating a stop condition.

This function initiates the TWI stop condition on the bus, signaling the end of the current communication frame. It sets the appropriate bits in the MCTRLB register to transmit the stop signal.

Note

The function waits until the stop condition has been executed by checking the BUSSTATE bits in the MSTATUS register. After this, the bus returns to the idle state, ready for the next communication cycle.