Header file with declarations and macros for software TWI/I2C. More...

#include <limits.h>
#include <avr/io.h>
#include <util/delay.h>
#include <avr/interrupt.h>
#include "../../../common/defines/TWI_defines.h"
#include "../../../common/enums/TWI_enums.h"

Include dependency graph for twi_soft.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	F_CPU 12000000UL
	System clock frequency definition.
#define	F_SOFT_TWI 100000UL
	TWI clock frequency definition.
#define	TWI_SOFT_CLOCK_PULSE_US (float)(1000000.0/(F_SOFT_TWI<<1))
	Duration of a half clock pulse in microseconds.
#define	TWI_SOFT_PULLUP_ENABLE
	Enable internal pull-up resistors for TWI lines.
#define	TWI_SOFT_DDR DDRB
	Data Direction Register for the TWI port.
#define	TWI_SOFT_PORT PORTB
	Port register for the TWI lines.
#define	TWI_SOFT_PIN PINB
	Port register for the TWI lines.
#define	TWI_SOFT_SCL PINB0
	Pin number for TWI Clock line (SCL).
#define	TWI_SOFT_SDA PINB1
	Pin number for TWI Data line (SDA).
#define	TWI_SOFT_STATUS_BUS_INIT_COMPLETE 0x00
#define	TWI_SOFT_STATUS_TRANSMIT 0x01
#define	TWI_SOFT_STATUS_RECEIVE 0x02
#define	TWI_SOFT_STATUS_BUS_ERROR 0xFF
#define	TWI_SOFT_BLOCK_IE
	Enable blocking of all system interrupts during TWI operations.
#define	SCL_LOW()
#define	SDA_LOW()
#define	SCL_HIGH()
#define	SDA_HIGH()

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.

Detailed Description

Header file with declarations and macros for software TWI/I2C.

This file provides function prototypes, type definitions, and constants for software-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"

Macro Definition Documentation

◆ F_CPU

#define F_CPU 12000000UL

System clock frequency definition.

This macro defines the operating frequency of the microcontroller's clock in Hertz. It is used by delay functions and timing calculations. The value should match the actual hardware clock frequency to ensure correct timing behavior in the software.

◆ F_SOFT_TWI

#define F_SOFT_TWI 100000UL

TWI clock frequency definition.

This macro defines the clock frequency used by the software-emulated TWI (I2C) implementation in Hertz. It sets the speed at which the software generates clock pulses for data transfer. Modifying this value affects the timing delays and the overall bus speed.

◆ TWI_SOFT_BLOCK_IE

#define TWI_SOFT_BLOCK_IE

Enable blocking of all system interrupts during TWI operations.

When defined, this macro causes the software TWI implementation to disable all system interrupts while a TWI transmission is in progress. This ensures uninterrupted communication on the TWI bus but may affect responsiveness to other interrupt-driven events. Use with caution to balance real-time requirements of the system.

Warning: All interrupts of the system will be blocked until the twi transmission is complete!

◆ TWI_SOFT_CLOCK_PULSE_US

#define TWI_SOFT_CLOCK_PULSE_US (float)(1000000.0/(F_SOFT_TWI<<1))

Duration of a half clock pulse in microseconds.

This macro calculates the length of one half clock pulse period in microseconds based on the configured TWI clock frequency (F_SOFT_TWI). his value is used to generate timing delays in the software TWI implementation to produce the desired clock signal frequency.

◆ TWI_SOFT_DDR

#define TWI_SOFT_DDR DDRB

Data Direction Register for the TWI port.

This macro defines which Data Direction Register (DDR) is used for the software TWI (I2C) implementation. It controls the direction (input/output) of the GPIO pins used for the TWI clock (SCL) and data (SDA) lines. By default, it is set to DDRB, but can be redefined to match the actual hardware pin configuration used in the project.

◆ TWI_SOFT_PIN

#define TWI_SOFT_PIN PINB

Port register for the TWI lines.

This macro defines the PORT register used for the software TWI (I2C) implementation on the AVR microcontroller. It is responsible for writing output values to the GPIO pins connected to the TWI clock (SCL) and data (SDA) lines. By default, it is set to PORTB, but can be redefined to match the actual hardware wiring in the project.

◆ TWI_SOFT_PORT

#define TWI_SOFT_PORT PORTB

Port register for the TWI lines.

This macro defines the PORT register used for the software TWI (I2C) implementation on the AVR microcontroller. It is responsible for writing output values to the GPIO pins connected to the TWI clock (SCL) and data (SDA) lines. By default, it is set to PORTB, but can be redefined to match the actual hardware wiring in the project.

◆ TWI_SOFT_PULLUP_ENABLE

#define TWI_SOFT_PULLUP_ENABLE

Enable internal pull-up resistors for TWI lines.

Defining this macro enables the use of internal pull-up resistors on the SDA and SCL lines of the software TWI implementation. When enabled, the software configures the GPIO pins with internal pull-ups, eliminating the need for external pull-up resistors if the hardware supports it. If this macro is not defined, the software assumes external pull-up resistors are present and handles the lines differently.

◆ TWI_SOFT_SCL

#define TWI_SOFT_SCL PINB0

Pin number for TWI Clock line (SCL).

This macro defines the specific pin number on the port that is used for the software TWI clock line (SCL) in the AVR microcontroller. By default, it is set to PINB0, but can be redefined to fit the hardware

◆ TWI_SOFT_SDA

#define TWI_SOFT_SDA PINB1

Pin number for TWI Data line (SDA).

This macro defines the specific pin number on the port that is used for the software TWI data line (SDA) in the AVR microcontroller. By default, it is set to PINB1, but can be redefined to fit the hardware

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

◆ 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

< 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

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ F_CPU

◆ F_SOFT_TWI

◆ TWI_SOFT_BLOCK_IE

◆ TWI_SOFT_CLOCK_PULSE_US

◆ TWI_SOFT_DDR

◆ TWI_SOFT_PIN

◆ TWI_SOFT_PORT

◆ TWI_SOFT_PULLUP_ENABLE

◆ TWI_SOFT_SCL

◆ TWI_SOFT_SDA

Function Documentation

◆ twi_soft_address()

◆ twi_soft_disable()

◆ twi_soft_get()

◆ twi_soft_init()

◆ twi_soft_set()

◆ twi_soft_start()

◆ twi_soft_status()

◆ twi_soft_stop()