twi_soft.c File Reference

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

#include "twi_soft.h"

Include dependency graph for twi_soft.c:

Functions
unsigned char	twi_soft_init (void)
	Initialize the software TWI (I2C) bus.
void	twi_soft_disable (void)
	Disable the software TWI (I2C) interface.
unsigned char	twi_soft_status (void)
	Get the current status of the software TWI bus.
TWI_Error	twi_soft_start (void)
	Generate a TWI start or repeated start condition.
void	twi_soft_stop (void)
	Stop the TWI (I2C) transmission.
TWI_Error	twi_soft_address (unsigned char address, TWI_Operation operation)
	Sends the slave address with the read/write operation on the TWI bus.
TWI_Error	twi_soft_set (unsigned char data)
	Transmit a byte of data on the TWI bus.
TWI_Error	twi_soft_get (unsigned char *data, TWI_Acknowledge acknowledge)
	Reads a byte of data from the TWI bus and sends an ACK or NACK.

Variables
unsigned char	twi_soft_bus_status

Detailed Description

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

This file contains the definitions of function implementations and macros for software-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_soft_address()

TWI_Error twi_soft_address	(	unsigned char	address,
		TWI_Operation	operation )

Sends the slave address with the read/write operation on the TWI bus.

Parameters

address	7-bit address of the slave device.
operation	Specifies the operation type: TWI_Write or TWI_Read.

Returns

Returns TWI_None if addressing was successful, TWI_Arbitration if arbitration was lost during transmission, or TWI_General if a general error occurred.

This function prepares and sends the 8-bit address byte on the TWI bus, combining the 7-bit slave address shifted left by 1 with the least significant bit indicating the operation (read or write). The actual transmission and status handling is performed by twi_soft_set().

Here is the call graph for this function:

twi_soft_disable()

void twi_soft_disable

(

void

)

Disable the software TWI (I2C) interface.

This function disables the software TWI module by clearing the SDA and SCL bits in the port and data direction registers. This effectively releases control of the TWI lines and sets the pins to a low output state. Use this function to safely deactivate the TWI bus when it is no longer needed.

twi_soft_get()

TWI_Error twi_soft_get	(	unsigned char *	data,
		TWI_Acknowledge	acknowledge )

Reads a byte of data from the TWI bus and sends an ACK or NACK.

Parameters

data	Pointer to a variable where the received data byte will be stored.
acknowledge	Specifies whether to send an ACK (TWI_ACK) or NACK (TWI_NACK) after reception.

Returns

Returns TWI_None if the data byte was received successfully, or TWI_General for other errors.

This function reads one data byte from the software TWI bus by manually controlling the clock and data lines. After reception, it sends either an acknowledgment (ACK) or not-acknowledgment (NACK) bit to the transmitter depending on the 'acknowledge' parameter, following the TWI protocol.

twi_soft_init()

unsigned char twi_soft_init

(

void

)

Initialize the software TWI (I2C) bus.

Returns

Returns TWI_SOFT_STATUS_BUS_INIT_COMPLETE if the bus was successfully initialized, or TWI_SOFT_STATUS_BUS_ERROR if a bus initialization error occurred.

This function initializes the software TWI bus by configuring the SDA and SCL lines to their idle high state and checking if the bus lines are free (not held low). It introduces delays to ensure proper timing according to the configured TWI clock pulse duration. If either the SCL or SDA line is stuck low, the function returns a bus error status. Otherwise, it confirms that the bus has been initialized successfully.

< Bus error occurred

< Bus initialization complete

twi_soft_set()

TWI_Error twi_soft_set

(

unsigned char

data

)

Transmit a byte of data on the TWI bus.

Parameters

data	The data byte to be transmitted.

Returns

Returns TWI_None if the data was successfully transmitted and acknowledged, TWI_Arbitration if arbitration was lost during transmission, or TWI_General if a general error occurred.

This function sends the given 8-bit data byte bit-by-bit over the software TWI bus, handling the clock and data line states manually. It checks for arbitration loss when transmitting 1 bits and waits for clock stretching by the slave. After transmission, it reads the acknowledgment bit from the slave to determine successful reception.

twi_soft_start()

TWI_Error twi_soft_start

(

void

)

Generate a TWI start or repeated start condition.

Returns

Returns TWI_None to indicate the start condition was initiated successfully.

This function produces a start condition on the TWI (I2C) bus which is used to initiate communication with a slave device. It sets the data line (SDA) low while the clock line (SCL) is high, creating the required falling edge signaling the start condition.

Note

Unlike a normal start function that requires the bus to be free, this implementation does not check the bus state and thus can also generate a repeated start condition if invoked during an ongoing transmission without issuing a stop condition first.

Attention

Interrupts can be blocked during the critical timing to ensure precise signal timing if the TWI_SOFT_BLOCK_IE macro is defined.

< Transmission running

twi_soft_status()

unsigned char twi_soft_status ( void )

inline

Get the current status of the software TWI bus.

Returns

The status byte indicating the current state of the TWI bus.

This inline function returns the value of the internal status variable twi_soft_bus_status which reflects the current operational state or error conditions of the software TWI interface.

twi_soft_stop()

void twi_soft_stop

(

void

)

Stop the TWI (I2C) transmission.

This function generates the TWI stop condition by first pulling both SCL and SDA lines low, then releasing SCL high, followed by releasing SDA high, with appropriate delays to ensure bus timing compliance. After sending the stop condition, the transmit status flag is cleared to indicate the end of the transmission.

< Transmission running

Variable Documentation

twi_soft_bus_status

unsigned char twi_soft_bus_status