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 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/avr "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.

Note: The function relies on twi_set for the actual data transmission and error checking.

Here is the call graph for this function:

◆ twi_disable()

void twi_disable ( void )

Disable the TWI (I2C) interface.

This 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.

Here is the caller graph for this function:

◆ 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.

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 TWINT flag. The received data is then read from the TWDR register and stored at the provided pointer.

The function checks the TWI status register (TWSR) for arbitration loss or to verify that the appropriate ACK/NACK status was received. If the received status matches the expected acknowledge mode, it returns success; otherwise, it indicates an acknowledgment error.

◆ 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 in master mode.

In master mode, it sets the bitrate and prescaler according to predefined macros.

Note: If TWI interrupt processing is enabled (TWI_TWIE), interrupts are activated.

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

Here is the call graph for this function:

Here is the caller 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 and triggers the transmission by setting the TWINT and TWEN bits in the control register.

Note: The function waits for the transmission to complete by polling the TWINT flag.

After transmission, the function reads the TWI status register (TWSR) to determine the outcome of the transmission and returns the corresponding status code.

Here is the caller graph for this function:

◆ twi_start()

TWI_Error twi_start ( void )

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

Returns: Returns TWI_None if the start condition was successfully transmitted (including repeated start), or TWI_Start if the start condition failed.

This function triggers the TWI hardware to send a START condition on the bus, signaling the beginning of a new communication frame. It sets the necessary control bits in the TWCR register to initiate the start and enables the TWI interface.

Note: The function then waits for the TWINT flag to indicate completion of the start condition transmission.

After completion, the function checks the TWI status register (TWSR) to verify if the start or repeated start condition was acknowledged by the bus. If successful, it returns TWI_None; otherwise, it returns TWI_Start indicating failure to send the (repeated) start condition.

◆ 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).

Here is the caller graph for this function:

◆ 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 TWCR register to transmit the stop signal and keeps the TWI hardware enabled.

Note: The function waits until the stop condition has been executed by checking the TWSTO bit in the control register. After this, the bus returns to the idle state, ready for the next communication cycle.

Functions

Detailed Description

Function Documentation

◆ twi_address()

◆ twi_disable()

◆ twi_get()

◆ twi_init()

◆ twi_set()

◆ twi_start()

◆ twi_status()

◆ twi_stop()