BSP430  20141115
Board Support Package for MSP430 microcontrollers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
onewire.h File Reference

Basic support for 1-Wire(R) communications. More...

#include <bsp430/periph/port.h>

Go to the source code of this file.

Data Structures

struct  sBSP430onewireBus
 
struct  sBSP430onewireSerialNumber
 

Macros

#define BSP430_ONEWIRE_xCel_TO_ddegF(xcel_)   (320 + ((9 * (xcel_)) / 8))
 
#define BSP430_ONEWIRE_xCel_TO_dK(xcel_)   ((21852U + 5U * (xcel_)) / 8U)
 

Typedefs

typedef struct sBSP430onewireBus sBSP430onewireBus
 
typedef struct sBSP430onewireSerialNumber sBSP430onewireSerialNumber
 

Enumerations

enum  {
  BSP430_ONEWIRE_CMD_READ_ROM = 0x33, BSP430_ONEWIRE_CMD_SKIP_ROM = 0xcc, BSP430_ONEWIRE_CMD_READ_POWER_SUPPLY = 0xb4, BSP430_ONEWIRE_CMD_RECALL_EE = 0xb8,
  BSP430_ONEWIRE_CMD_READ_SCRATCHPAD = 0xbe, BSP430_ONEWIRE_CMD_CONVERT_T = 0x44
}
 

Functions

int iBSP430onewireReset_ni (const sBSP430onewireBus *bus)
 
void vBSP430onewireShutdown_ni (const sBSP430onewireBus *bus)
 
void vBSP430onewireWriteByte_ni (const sBSP430onewireBus *bus, int byte)
 
int iBSP430onewireReadBit_ni (const sBSP430onewireBus *bus)
 
int iBSP430onewireReadByte_ni (const sBSP430onewireBus *bus)
 
int iBSP430onewireComputeCRC (const unsigned char *data, int len)
 
int iBSP430onewireReadSerialNumber (const sBSP430onewireBus *bus, sBSP430onewireSerialNumber *snp)
 
int iBSP430onewireReadPowerSupply (const sBSP430onewireBus *bus)
 
int iBSP430onewireRequestTemperature_ni (const sBSP430onewireBus *bus)
 
static BSP430_CORE_INLINE int iBSP430onewireTemperatureReady_ni (const sBSP430onewireBus *bus)
 
int iBSP430onewireReadTemperature_ni (const sBSP430onewireBus *bus, int *temp_xCel)
 

Detailed Description

Basic support for 1-Wire(R) communications.

This currently supports enough to use DS18X one-wire temperature sensors with a dedicated bus and external power. Multiple devices on the bus, and parasite powered devices, have not been tested.

Homepage
http://github.com/pabigot/bsp430

Macro Definition Documentation

#define BSP430_ONEWIRE_xCel_TO_ddegF (   xcel_)    (320 + ((9 * (xcel_)) / 8))

Convert temperature from 1/16th Cel to tenths Fahrhenheit (d[degF])

For those of us who live in the US.

9 * t / 8 == (9/5) * 10 * (t / 16) without incidental overflow

Examples:
sensors/ds18b20/main.c.
#define BSP430_ONEWIRE_xCel_TO_dK (   xcel_)    ((21852U + 5U * (xcel_)) / 8U)

Convert temperature from 1/16th Cel to tenths Kelvin (dK)

For those of us who obey the instruction of the Unified Code for Units of Measure

10 * (273.15 + x / 16) = (16*27315 + 100*x) / 160 = (437040 + 100 * x) / 160 = (21852 + 5 * x) / 8

Typedef Documentation

Structure identifying 1-wire bus information.

Structure holding a 1-wire serial number.

Enumeration Type Documentation

anonymous enum
Enumerator
BSP430_ONEWIRE_CMD_READ_ROM 

Read 64-bit ROM code without using search procedure

BSP430_ONEWIRE_CMD_SKIP_ROM 

Skip ROM sends the following command to all bus devices

BSP430_ONEWIRE_CMD_READ_POWER_SUPPLY 

Determine whether device is parasite-powered or external-powered

BSP430_ONEWIRE_CMD_RECALL_EE 

Store data from EEPROM into RAM

BSP430_ONEWIRE_CMD_READ_SCRATCHPAD 

Read the RAM area.

BSP430_ONEWIRE_CMD_CONVERT_T 

Initiate a temperature conversion.

Be aware that temperature conversion can take up to 750ms at the default 12-bit resolution.

For an externally (non-parasite) powered sensor, the caller may use iBSP430onewireReadBit_ni to determine whether the conversion has completed. Completion is indicated when the device responds with a 1.

Function Documentation

int iBSP430onewireComputeCRC ( const unsigned char *  data,
int  len 
)

Calculate the CRC over the data.

When the last byte of the data is the CRC of the preceding bytes, the return value of this function should be zero.

Parameters
datadata for which CRC is desired
lenthe number of bytes that contribute to CRC calculation
Returns
the calculated CRC value
int iBSP430onewireReadBit_ni ( const sBSP430onewireBus bus)

Read a bit from the 1-wire bus.

Parameters
busThe port and bit identifying the 1-wire bus
Returns
The value of the bit read (0 or 1).
Examples:
sensors/ds18b20/main.c.
int iBSP430onewireReadByte_ni ( const sBSP430onewireBus bus)

Read a byte from the 1-wire bus.

Invokes iBSP430onewireReadBit_ni eight times to read the data, least significant bit first.

Parameters
busThe port and bit identifying the 1-wire bus
Returns
The value of the byte read (0 to 255).
int iBSP430onewireReadPowerSupply ( const sBSP430onewireBus bus)

Determine whether device is externally powered or uses parasite power.

Parameters
busThe port and bit identifying the 1-wire bus
Returns
1 if the bus is externally powered; 0 if the bus is parasitically powered; a negative value if an error is encountered.
Examples:
sensors/ds18b20/main.c.
int iBSP430onewireReadSerialNumber ( const sBSP430onewireBus bus,
sBSP430onewireSerialNumber snp 
)

Read the serial number from a 1-wire device.

Parameters
busThe port and bit identifying the 1-wire bus
snpPointer to where the serial number should be stored
Returns
0 if the serial number was successfully read; -1 if an error occurred.
Examples:
sensors/ds18b20/main.c.
int iBSP430onewireReadTemperature_ni ( const sBSP430onewireBus bus,
int *  temp_xCel 
)

Read the most recent temperature measurement

The temperature is a signed 16-bit value representing 1/16th degrees Celcius. I.e., a value of 1 is 0.0625 Cel.

Note
The accuracy and precision of the measurement are much more coarse than its resolution.
Parameters
busThe port and bit identifying the 1-wire bus
temp_xCelPointer to a location into which the temperature will be written. This must not be null.
Returns
0 if the read was successful; -1 if an error occurred. If there was an error, the value pointed to by temp_xCel remains unchanged.
Examples:
sensors/ds18b20/main.c.
int iBSP430onewireRequestTemperature_ni ( const sBSP430onewireBus bus)

Send the command sequence to initiate a temperature measurement

Note that this simply requests that the device start to measure the temperature. The measurement process may take up to 750 msec at the default 12-bit resolution.

If the device is externally powered, iBSP430onewireTemperatureReady_ni() can be invoked to determine whether the requested measurement has completed. If using parasitic power, the application should wait for at least the maximum sample time before invoking iBSP430onewireReadTemperature_ni().

Parameters
busThe port and bit identifying the 1-wire bus
Returns
0 if the request was successfully submitted, -1 if an error occured.
Examples:
sensors/ds18b20/main.c.
int iBSP430onewireReset_ni ( const sBSP430onewireBus bus)

Reset the bus and check for device presence.

This executes the 1-wire bus reset protocol, then detects whether a 1-wire device is present. The protocol requires that the bus be held low for a given period, then returns it to pullup input. A device present on the bus will respond by pulling the bus low.

Parameters
busThe port and bit identifying the 1-wire bus
Returns
0 if no device was detected, 1 if a device responded to the reset.
static BSP430_CORE_INLINE int iBSP430onewireTemperatureReady_ni ( const sBSP430onewireBus bus)
static

Test whether the device has completed measuring the temperature

Parameters
busThe port and bit identifying the 1-wire bus
Note
Do not invoke this for parasitically-powered devices. See iBSP430onewireRequestTemperature_ni().
Returns
0 if the device is still busy; 1 if the sample is ready.
void vBSP430onewireShutdown_ni ( const sBSP430onewireBus bus)

Configure the bus pin for low power mode.

This reconfigures the port as output low. Note that this affects the MCU power, not the device power. It does remove power from parasitic devices, but externally powered devices will still draw some amount of current.

Parameters
busThe port and bit identifying the 1-wire bus
Examples:
sensors/ds18b20/main.c.
void vBSP430onewireWriteByte_ni ( const sBSP430onewireBus bus,
int  byte 
)

Write a byte onto the 1-wire bus.

Parameters
busThe port and bit identifying the 1-wire bus
byteThe value to be written. The low 8 bits are transmitted LSB-first.