Onewire_api

Macros
#define	ONEWIRE_TXN_MASK
#define	ONEWIRE_TXN_SIZE_LSHIFT   3
#define	ONEWIRE_TXN_BSIZE_LSHIFT   16
#define	ONEWIRE_INIT_SPD_STD   0x00000000
#define	ONEWIRE_INIT_SPD_OD   0x00000020
#define	ONEWIRE_INIT_READ_STD   0x00000000
#define	ONEWIRE_INIT_READ_LATE   0x00000040
#define	ONEWIRE_INIT_ATR   0x00000000
#define	ONEWIRE_INIT_NO_ATR   0x00000080
#define	ONEWIRE_INIT_STD_POL   0x00000000
#define	ONEWIRE_INIT_ALT_POL   0x40000000
#define	ONEWIRE_INIT_1_WIRE_CFG   0x00000000
#define	ONEWIRE_INIT_2_WIRE_CFG   0x80000000
#define	ONEWIRE_BUS_STATUS_BUSY   0x00000100
#define	ONEWIRE_BUS_STATUS_NO_SLAVE   0x00000200
#define	ONEWIRE_BUS_STATUS_STUCK   0x00000400
#define	ONEWIRE_OP_RESET   0x00000001
#define	ONEWIRE_OP_READ   0x00000002
#define	ONEWIRE_OP_WRITE   0x00000004
#define	ONEWIRE_DMA_BUS_RESET   0x00000001
#define	ONEWIRE_DMA_OP_READ   0x00000002
#define	ONEWIRE_DMA_OP_MULTI_WRITE   0x00000004
#define	ONEWIRE_DMA_OP_MULTI_READ   0x00000006
#define	ONEWIRE_DMA_MODE_SG   0x00000008
#define	ONEWIRE_DMA_OP_SZ_8   0x00000000
#define	ONEWIRE_DMA_OP_SZ_16   0x00000800
#define	ONEWIRE_DMA_OP_SZ_32   0x00001800
#define	ONEWIRE_INT_RESET_DONE   0x00000001
#define	ONEWIRE_INT_OP_DONE   0x00000002
#define	ONEWIRE_INT_NO_SLAVE   0x00000004
#define	ONEWIRE_INT_STUCK   0x00000008
#define	ONEWIRE_INT_DMA_DONE   0x00000010

Functions
void	OneWireInit (uint32_t ui32Base, uint32_t ui32InitFlags)
void	OneWireBusReset (uint32_t ui32Base)
uint32_t	OneWireBusStatus (uint32_t ui32Base)
void	OneWireDataGet (uint32_t ui32Base, uint32_t *pui32Data)
bool	OneWireDataGetNonBlocking (uint32_t ui32Base, uint32_t *pui32Data)
void	OneWireIntClear (uint32_t ui32Base, uint32_t ui32IntFlags)
void	OneWireIntDisable (uint32_t ui32Base, uint32_t ui32IntFlags)
void	OneWireIntEnable (uint32_t ui32Base, uint32_t ui32IntFlags)
uint32_t	OneWireIntStatus (uint32_t ui32Base, bool bMasked)
void	OneWireIntRegister (uint32_t ui32Base, void(*pfnHandler)(void))
void	OneWireIntUnregister (uint32_t ui32Base)
void	OneWireDMADisable (uint32_t ui32Base, uint32_t ui32DMAFlags)
void	OneWireDMAEnable (uint32_t ui32Base, uint32_t ui32DMAFlags)
void	OneWireTransaction (uint32_t ui32Base, uint32_t ui32OpMode, uint32_t ui32Data, uint32_t ui32BitCnt)

Detailed Description

Introduction

The 1-Wire API provides functions to use the 1-Wire Master module in the MSP432E4 microcontroller.

The 1-Wire specification defines a bi-directional serial communication protocol that provides both power and data over a single wire. The 1-Wire Master module can interface with one or more slave devices. Typical slave devices include thermometers, mixed-signal devices, memory, and authentication devices.

Some features of the 1-Wire Master module include:

• Support for standard and overdrive speeds, including a late-sample mechanism
• Data size transfers of 1, 2, 3, or 4 bytes with sub-byte support
• Interrupt capability for transaction pacing and line error

Programming Example

The following example sets up the 1-Wire Master module and sends a command sequence over a single slave device connection. A connection with multiple slave devices would require enumeration and selection of an individual device. This example assumes that the interrupt handler was allocated statically in the vector table and the GPIOs are properly configured.

//
// Enable the 1-Wire peripheral
//
SysCtlPeripheralEnable(SYSCTL_PERIPH_ONEWIRE0);

//
// Wait for the 1-Wire module to be ready.
//
while(!SysCtlPeripheralReady(SYSCTL_PERIPH_ONEWIRE0))
{
}

//
// Initialize the module to use standard speed and read distance.
//
OneWireInit(ONEWIRE0_BASE, (ONEWIRE_INIT_READ_STD | ONEWIRE_INIT_SPD_STD));

//
// Clear any pending interrupts.
//
OneWireIntClear(ONEWIRE0_BASE, (ONEWIRE_INT_STUCK | ONEWIRE_INT_NO_SLAVE |
                               ONEWIRE_INT_RESET_DONE |
                               ONEWIRE_INT_OP_DONE));

//
// Enable the interrupts for operation done and the stuck bus error
// condition.
//
OneWireIntEnable(ONEWIRE0_BASE, (ONEWIRE_INT_OP_DONE |
                                 ONEWIRE_INT_BUS_STUCK));
IntEnable(INT_ONEWIRE0);

//
// Setup a four byte sequence and a bit count.
//
ulData = ((0x01 << 24) | (0x12 << 16) | (0x10 << 8) | 0xcc;
ulBitCount = sizeof(ulData) * 8;

//
// Initiate a Reset and Write operation on the 1-Wire bus.
//
OneWireTransaction(ONEWIRE0_BASE, (ONEWIRE_OP_RESET | ONEWIRE_OP_WRITE),
                   ulData, ulBitCount);

Macro Definition Documentation

ONEWIRE_TXN_MASK

#define ONEWIRE_TXN_MASK

Value:

(ONEWIRE_CS_OP_M | ONEWIRE_CS_SZ_M |          \
                                 ONEWIRE_CS_BSIZE_M)

Referenced by OneWireDMADisable(), OneWireDMAEnable(), and OneWireTransaction().

ONEWIRE_TXN_SIZE_LSHIFT

#define ONEWIRE_TXN_SIZE_LSHIFT   3

Referenced by OneWireTransaction().

ONEWIRE_TXN_BSIZE_LSHIFT

#define ONEWIRE_TXN_BSIZE_LSHIFT   16

Referenced by OneWireTransaction().

ONEWIRE_INIT_SPD_STD

#define ONEWIRE_INIT_SPD_STD   0x00000000

ONEWIRE_INIT_SPD_OD

#define ONEWIRE_INIT_SPD_OD   0x00000020

ONEWIRE_INIT_READ_STD

#define ONEWIRE_INIT_READ_STD   0x00000000

ONEWIRE_INIT_READ_LATE

#define ONEWIRE_INIT_READ_LATE   0x00000040

ONEWIRE_INIT_ATR

#define ONEWIRE_INIT_ATR   0x00000000

ONEWIRE_INIT_NO_ATR

#define ONEWIRE_INIT_NO_ATR   0x00000080

ONEWIRE_INIT_STD_POL

#define ONEWIRE_INIT_STD_POL   0x00000000

ONEWIRE_INIT_ALT_POL

#define ONEWIRE_INIT_ALT_POL   0x40000000

ONEWIRE_INIT_1_WIRE_CFG

#define ONEWIRE_INIT_1_WIRE_CFG   0x00000000

ONEWIRE_INIT_2_WIRE_CFG

#define ONEWIRE_INIT_2_WIRE_CFG   0x80000000

ONEWIRE_BUS_STATUS_BUSY

#define ONEWIRE_BUS_STATUS_BUSY   0x00000100

ONEWIRE_BUS_STATUS_NO_SLAVE

#define ONEWIRE_BUS_STATUS_NO_SLAVE   0x00000200

ONEWIRE_BUS_STATUS_STUCK

#define ONEWIRE_BUS_STATUS_STUCK   0x00000400

ONEWIRE_OP_RESET

#define ONEWIRE_OP_RESET   0x00000001

Referenced by OneWireTransaction().

ONEWIRE_OP_READ

#define ONEWIRE_OP_READ   0x00000002

Referenced by OneWireTransaction().

ONEWIRE_OP_WRITE

#define ONEWIRE_OP_WRITE   0x00000004

Referenced by OneWireTransaction().

ONEWIRE_DMA_BUS_RESET

#define ONEWIRE_DMA_BUS_RESET   0x00000001

ONEWIRE_DMA_OP_READ

#define ONEWIRE_DMA_OP_READ   0x00000002

ONEWIRE_DMA_OP_MULTI_WRITE

#define ONEWIRE_DMA_OP_MULTI_WRITE   0x00000004

ONEWIRE_DMA_OP_MULTI_READ

#define ONEWIRE_DMA_OP_MULTI_READ   0x00000006

ONEWIRE_DMA_MODE_SG

#define ONEWIRE_DMA_MODE_SG   0x00000008

ONEWIRE_DMA_OP_SZ_8

#define ONEWIRE_DMA_OP_SZ_8   0x00000000

ONEWIRE_DMA_OP_SZ_16

#define ONEWIRE_DMA_OP_SZ_16   0x00000800

ONEWIRE_DMA_OP_SZ_32

#define ONEWIRE_DMA_OP_SZ_32   0x00001800

ONEWIRE_INT_RESET_DONE

#define ONEWIRE_INT_RESET_DONE   0x00000001

ONEWIRE_INT_OP_DONE

#define ONEWIRE_INT_OP_DONE   0x00000002

ONEWIRE_INT_NO_SLAVE

#define ONEWIRE_INT_NO_SLAVE   0x00000004

ONEWIRE_INT_STUCK

#define ONEWIRE_INT_STUCK   0x00000008

ONEWIRE_INT_DMA_DONE

#define ONEWIRE_INT_DMA_DONE   0x00000010

Function Documentation

OneWireInit()

void OneWireInit	(	uint32_t	ui32Base,
		uint32_t	ui32InitFlags
	)

Initializes the 1-Wire module.

Parameters

ui32Base	specifies the base address of the 1-Wire module.
ui32InitFlags	provides the initialization flags.

This function configures and initializes the 1-Wire interface for use.

The ui32InitFlags parameter is a combination of the following:

• ONEWIRE_INIT_SPD_STD - standard speed bus timings
• ONEWIRE_INIT_SPD_OD - overdrive speed bus timings
• ONEWIRE_INIT_READ_STD - standard read sampling timing
• ONEWIRE_INIT_READ_LATE - late read sampling timing
• ONEWIRE_INIT_ATR - standard answer-to-reset presence detect
• ONEWIRE_INIT_NO_ATR - no answer-to-reset presence detect
• ONEWIRE_INIT_STD_POL - normal signal polarity
• ONEWIRE_INIT_ALT_POL - alternate (reverse) signal polarity
• ONEWIRE_INIT_1_WIRE_CFG - standard 1-Wire (1 data pin) setup
• ONEWIRE_INIT_2_WIRE_CFG - alternate 2-Wire (2 data pin) setup

Returns

None.

References ASSERT, HWREG, and ONEWIRE_O_CS.

OneWireBusReset()

void OneWireBusReset

(

uint32_t

ui32Base

)

Issues a reset on the 1-Wire bus.

Parameters

ui32Base

specifies the base address of the 1-Wire module.

This function causes the 1-Wire module to generate a reset signal on the 1-Wire bus.

Returns

None.

References ASSERT, HWREG, ONEWIRE_CS_RST, and ONEWIRE_O_CS.

OneWireBusStatus()

uint32_t OneWireBusStatus

(

uint32_t

ui32Base

)

Retrieves the 1-Wire bus condition status.

Parameters

ui32Base

specifies the base address of the 1-Wire module.

This function returns the 1-Wire bus conditions reported by the 1-Wire module. These conditions could be a logical OR of any of the following:

• ONEWIRE_BUS_STATUS_BUSY - A read, write, or reset is active.
• ONEWIRE_BUS_STATUS_NO_SLAVE - No slave presence pulses detected.
• ONEWIRE_BUS_STATUS_STUCK - The bus is being held low by non-master.

Returns

Returns the 1-Wire bus conditions if detected else zero.

References ASSERT, HWREG, ONEWIRE_CS_BUSY, ONEWIRE_CS_NOATR, ONEWIRE_CS_STUCK, and ONEWIRE_O_CS.

OneWireDataGet()

void OneWireDataGet	(	uint32_t	ui32Base,
		uint32_t *	pui32Data
	)

Retrieves data from the 1-Wire interface.

Parameters

ui32Base	specifies the base address of the 1-Wire module.
pui32Data	is a pointer to storage to hold the read data.

This function reads data from the 1-Wire module once all active bus operations are completed. By protocol definition, bit data defaults to a 1. Thus if a slave did not signal any 0-bit data, this read returns 0xffffffff.

Returns

None.

References ASSERT, HWREG, ONEWIRE_CS_BUSY, ONEWIRE_O_CS, and ONEWIRE_O_DATR.

OneWireDataGetNonBlocking()

bool OneWireDataGetNonBlocking	(	uint32_t	ui32Base,
		uint32_t *	pui32Data
	)

Retrieves data from the 1-Wire interface.

Parameters

ui32Base	specifies the base address of the 1-Wire module.
pui32Data	is a pointer to storage to hold the read data.

This function reads data from the 1-Wire module if there are no active operations on the bus. Otherwise it returns without reading the data from the module.

By protocol definition, bit data defaults to a 1. Thus if a slave did not signal any 0-bit data, this read returns 0xffffffff.

Returns

Returns true if a data read was performed, or false if the bus was not idle and no data was read.

References ASSERT, HWREG, ONEWIRE_CS_BUSY, ONEWIRE_O_CS, and ONEWIRE_O_DATR.

OneWireIntClear()

void OneWireIntClear	(	uint32_t	ui32Base,
		uint32_t	ui32IntFlags
	)

Clears the 1-Wire module interrupt sources.

Parameters

ui32Base	specifies the base address of the 1-Wire module.
ui32IntFlags	is a bit mask of the interrupt sources to be cleared.

This function clears the specified 1-Wire interrupt sources so that they no longer assert. This function must be called in the interrupt handler to keep the interrupts from being triggered again immediately upon exit. The ui32IntFlags parameter can be a logical OR of any of the following:

• ONEWIRE_INT_RESET_DONE - Bus reset has just completed.
• ONEWIRE_INT_OP_DONE - Read or write operation completed. If a combined write and read operation was set up, the interrupt signals the read is done.
• ONEWIRE_INT_NO_SLAVE - No presence detect was signaled by a slave.
• ONEWIRE_INT_STUCK - Bus is being held low by non-master.
• ONEWIRE_INT_DMA_DONE - DMA operation has completed.

Note

Because there is a write buffer in the Cortex-M processor, it may take several clock cycles before the interrupt source is actually cleared. Therefore, it is recommended that the interrupt source be cleared early in the interrupt handler (as opposed to the very last action) to avoid returning from the interrupt handler before the interrupt source is actually cleared. Failure to do so may result in the interrupt handler being immediately reentered (because the interrupt controller still sees the interrupt source asserted).

Returns

None.

References ASSERT, HWREG, ONEWIRE_IM_DMA, ONEWIRE_IM_NOATR, ONEWIRE_IM_OPC, ONEWIRE_IM_RST, ONEWIRE_IM_STUCK, and ONEWIRE_O_ICR.

OneWireIntDisable()

void OneWireIntDisable	(	uint32_t	ui32Base,
		uint32_t	ui32IntFlags
	)

Disables individual 1-Wire module interrupt sources.

Parameters

ui32Base	specifies the base address of the 1-Wire module.
ui32IntFlags	is a bit mask of the interrupt sources to be disabled.

This function disables the indicated 1-Wire interrupt sources. The ui32IntFlags parameter can be a logical OR of any of the following:

• ONEWIRE_INT_RESET_DONE - Bus reset has just completed.
• ONEWIRE_INT_OP_DONE - Read or write operation completed. If a combined write and read operation was set up, the interrupt signals the read is done.
• ONEWIRE_INT_NO_SLAVE - No presence detect was signaled by a slave.
• ONEWIRE_INT_STUCK - Bus is being held low by non-master.
• ONEWIRE_INT_DMA_DONE - DMA operation has completed

Returns

None.

References ASSERT, HWREG, ONEWIRE_IM_DMA, ONEWIRE_IM_NOATR, ONEWIRE_IM_OPC, ONEWIRE_IM_RST, ONEWIRE_IM_STUCK, and ONEWIRE_O_IM.

OneWireIntEnable()

void OneWireIntEnable	(	uint32_t	ui32Base,
		uint32_t	ui32IntFlags
	)

Enables individual 1-Wire module interrupt sources.

Parameters

ui32Base	specifies the base address of the 1-Wire module.
ui32IntFlags	is a bit mask of the interrupt sources to be enabled.

This function enables the indicated 1-Wire interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt; disabled sources have no effect on the processor. The ui32IntFlags parameter can be a logical OR of any of the following:

• ONEWIRE_INT_RESET_DONE - Bus reset has just completed.
• ONEWIRE_INT_OP_DONE - Read or write operation completed. If a combined write and read operation was set up, the interrupt signals the read is done.
• ONEWIRE_INT_NO_SLAVE - No presence detect was signaled by a slave.
• ONEWIRE_INT_STUCK - Bus is being held low by non-master.
• ONEWIRE_INT_DMA_DONE - DMA operation has completed

Returns

None.

References ASSERT, HWREG, ONEWIRE_IM_DMA, ONEWIRE_IM_NOATR, ONEWIRE_IM_OPC, ONEWIRE_IM_RST, ONEWIRE_IM_STUCK, and ONEWIRE_O_IM.

OneWireIntStatus()

uint32_t OneWireIntStatus	(	uint32_t	ui32Base,
		bool	bMasked
	)

Gets the current 1-Wire interrupt status.

Parameters

ui32Base	specifies the base address of the 1-Wire module.
bMasked	is false if the raw interrupt status is required or true if the masked interrupt status is required.

This function returns the interrupt status for the 1-Wire module. Either the raw interrupt status or the status of interrupts that are allowed to reflect to the processor can be returned.

Returns

Returns the masked or raw 1-Wire interrupt status, as a bit field of any of the following values:

• ONEWIRE_INT_RESET_DONE - Bus reset has just completed.
• ONEWIRE_INT_OP_DONE - Read or write operation completed.
• ONEWIRE_INT_NO_SLAVE - No presence detect was signaled by a slave.
• ONEWIRE_INT_STUCK - Bus is being held low by non-master.
• ONEWIRE_INT_DMA_DONE - DMA operation has completed

References ASSERT, HWREG, ONEWIRE_O_MIS, and ONEWIRE_O_RIS.

OneWireIntRegister()

void OneWireIntRegister	(	uint32_t	ui32Base,
		void(*)(void)	pfnHandler
	)

Registers an interrupt handler for the 1-Wire module.

Parameters

ui32Base	is the base address of the 1-Wire module.
pfnHandler	is a pointer to the function to be called when the 1-Wire interrupt occurs.

This function sets the handler to be called when a 1-Wire interrupt occurs. This function enables the global interrupt in the interrupt controller; specific 1-Wire interrupts must be enabled via OneWireIntEnable(). If necessary, it is the interrupt handler's responsibility to clear the interrupt source via OneWireIntClear().

See also

IntRegister() for important information about registering interrupt handlers.

Returns

None.

References ASSERT.

OneWireIntUnregister()

void OneWireIntUnregister

(

uint32_t

ui32Base

)

Unregisters an interrupt handler for the 1-Wire module.

Parameters

ui32Base

is the base address of the 1-Wire module.

This function clears the handler to be called when an 1-Wire interrupt occurs. This function also masks off the interrupt in the interrupt controller so that the interrupt handler no longer is called.

See also

IntRegister() for important information about registering interrupt handlers.

Returns

None.

References ASSERT.

OneWireDMADisable()

void OneWireDMADisable	(	uint32_t	ui32Base,
		uint32_t	ui32DMAFlags
	)

Disables 1-Wire DMA operations.

Parameters

ui32Base	is the base address of the 1-Wire module.
ui32DMAFlags	is a bit mask of the DMA features to disable.

This function is used to disable 1-Wire DMA features that were enabled by OneWireDMAEnable(). The specified 1-Wire DMA features are disabled. The ui32DMAFlags parameter is a combination of the following:

• ONEWIRE_DMA_BUS_RESET - Issue a 1-Wire bus reset before starting
• ONEWIRE_DMA_OP_READ - Read after each module transaction
• ONEWIRE_DMA_OP_MULTI_WRITE - Write after each previous write
• ONEWIRE_DMA_OP_MULTI_READ - Read after each previous read
• ONEWIRE_DMA_MODE_SG - Start DMA on enable then repeat on each completion
• ONEWIRE_DMA_OP_SZ_8 - Bus read/write of 8 bits
• ONEWIRE_DMA_OP_SZ_16 - Bus read/write of 16 bits
• ONEWIRE_DMA_OP_SZ_32 - Bus read/write of 32 bits

Returns

None.

References ASSERT, HWREG, ONEWIRE_O_CS, ONEWIRE_O_DMA, and ONEWIRE_TXN_MASK.

OneWireDMAEnable()

void OneWireDMAEnable	(	uint32_t	ui32Base,
		uint32_t	ui32DMAFlags
	)

Enables 1-Wire DMA operations.

Parameters

ui32Base	is the base address of the 1-Wire module.
ui32DMAFlags	is a bit mask of the DMA features to enable.

This function enables the specified 1-Wire DMA features. The 1-Wire module can be configured for write operations, read operations, small write and read operations, and scatter-gather support of mixed operations.

The ui32DMAFlags parameter is a combination of the following:

• ONEWIRE_DMA_BUS_RESET - Issue a 1-Wire bus reset before starting
• ONEWIRE_DMA_OP_READ - Read after each module transaction
• ONEWIRE_DMA_OP_MULTI_WRITE - Write after each previous write
• ONEWIRE_DMA_OP_MULTI_READ - Read after each previous read
• ONEWIRE_DMA_MODE_SG - Start DMA on enable then repeat on each completion
• ONEWIRE_DMA_OP_SZ_8 - Bus read/write of 8 bits
• ONEWIRE_DMA_OP_SZ_16 - Bus read/write of 16 bits
• ONEWIRE_DMA_OP_SZ_32 - Bus read/write of 32 bits

Note

The uDMA controller must be properly configured before DMA can be used with the 1-Wire module.

Returns

None.

References ASSERT, HWREG, ONEWIRE_DMA_DMAOP_RDMUL, ONEWIRE_DMA_DMAOP_RDSNG, ONEWIRE_DMA_SG, ONEWIRE_O_CS, ONEWIRE_O_DATW, ONEWIRE_O_DMA, ONEWIRE_TXN_MASK, and SysCtlDelay().

OneWireTransaction()

void OneWireTransaction	(	uint32_t	ui32Base,
		uint32_t	ui32OpMode,
		uint32_t	ui32Data,
		uint32_t	ui32BitCnt
	)

Performs a 1-Wire protocol transaction on the bus.

Parameters

ui32Base	specifies the base address of the 1-Wire module.
ui32OpMode	sets the transaction type.
ui32Data	is the data for a write operation.
ui32BitCnt	specifies the number of valid bits (1-32) for the operation.

This function performs a 1-Wire protocol transaction, read and/or write, on the bus. The application should confirm the bus is idle before starting a read or write transaction.

The ui32OpMode defines the activity for the bus operations and is a logical OR of the following:

• ONEWIRE_OP_RESET - Indicates the operation should be started with a bus reset.
• ONEWIRE_OP_WRITE - A write operation
• ONEWIRE_OP_READ - A read operation

Note

If both a read and write operation are requested, the write will be performed prior to the read.

Returns

None.

References ASSERT, HWREG, ONEWIRE_CS_OP_RD, ONEWIRE_CS_OP_WR, ONEWIRE_O_CS, ONEWIRE_O_DATW, ONEWIRE_OP_READ, ONEWIRE_OP_RESET, ONEWIRE_OP_WRITE, ONEWIRE_TXN_BSIZE_LSHIFT, ONEWIRE_TXN_MASK, and ONEWIRE_TXN_SIZE_LSHIFT.