Interface: tos.chips.msp430.adc12.Msp430Adc12SingleChannel

interface Msp430Adc12SingleChannel

This interface provides access to the ADC12 on the level of HAL. It can be used to sample a single adc channel once or repeatedly (one event is signalled per conversion result) or perform multiple conversions for a single channel once or repeatedly (one event is signalled per multiple conversion results). It cannot be used to sample different adc channels with a single command (use the Msp430Adc12MultiChannel interface instead). Sampling a channel requires calling a sequence of two commands, configureX() and getData(), where X is either 'Single', 'SingleRepeat', 'Multiple' or 'MultipleRepeat'. Conversion results will be signalled by the dataReadySingle() or dataReadyMultiple() event, depending on the previous configuration, i.e. there are four possible sequences:

configureSingle() -> ( getData() -> singleDataReady() )*

configureSingleRepeat() -> ( getData() -> singleDataReady() )*

configureMultiple() -> ( getData() -> multipleDataReady() )*

configureMultipleRepeat() -> getData() -> multipleDataReady()

where configureX() and getData() are commands called by the client and singleDataReady() and multipleDataReady() are events signalled back to the client by the adc subsystem. Note that a configuration is valid until the client reconfigures or releases the ADC (using the Resource interface), except for configureMultipleRepeat(), which is only valid for a single call to getData(). This means that after a successful configuration with, for example, configureSingle() the client may call getData() more than once without reconfiguring the ADC in between (if the client has not released the ADC via the Resource interface).

Author:: Jan Hauer

Commands

command error_t configureMultiple(msp430adc12_channel_config_t *config, uint16_t *buffer, uint16_t numSamples, uint16_t jiffies) Configures the ADC for sampling a channel numSamples times with a given sampling period.

command error_t configureMultipleRepeat(msp430adc12_channel_config_t *config, uint16_t *buffer, uint8_t numSamples, uint16_t jiffies) Configures the ADC for sampling a channel multiple times repeatedly.

command error_t configureSingle(msp430adc12_channel_config_t *config) Configures the ADC to perform a single conversion.

command error_t configureSingleRepeat(msp430adc12_channel_config_t *config, uint16_t jiffies) Configures the ADC for repeated single channel conversion mode.

command error_t getData() Starts sampling an adc channel using the configuration as specified by the last call to any of the four available configuration commands.

Events

event uint16_t *multipleDataReady(uint16_t *buffer, uint16_t numSamples) Multiple ADC conversion results are ready.

event error_t singleDataReady(uint16_t data) A single ADC conversion result is ready.

Commands - Details

configureMultiple

command error_t configureMultiple(msp430adc12_channel_config_t *config, uint16_t *buffer, uint16_t numSamples, uint16_t jiffies)

Configures the ADC for sampling a channel numSamples times with a given sampling period. Any previous configuration will be overwritten. In contrast to the configureSingleRepeat() command, this configuration means that only one event will be signalled after all samples have been taken (which is useful for high-frequency sampling). If SUCCESS is returned calling getData() will start sampling the adc channel numSamples times and the first conversion is started immediately. Conversion results are stored in a buffer allocated by the client (the buffer parameter). The sampling period is specified by the jiffies parameter, which defines the time between successive conversions in terms of clock ticks of clock source "sampcon_ssel" and clock input divider "sampcon_id" as specified in the config parameter. If jiffies is zero successive conversions are performed as quickly as possible. After numSamples conversions an event multipleDataReady() is signalled with the conversion results.

Parameters:: config - ADC12 configuration data.; jiffies - Sampling period in terms of clock ticks of "sampcon_ssel" and input divider "sampcon_id".; buffer - The user-allocated buffer in which the conversion results will be stored. It must have at least numSamples entries, i.e. it must have a size of at least numSamples * 2 byte.; numSamples - Number of adc samples
Returns:: SUCCESS means that the ADC was configured successfully and getData() can be called to start with the first conversion.

configureMultipleRepeat

command error_t configureMultipleRepeat(msp430adc12_channel_config_t *config, uint16_t *buffer, uint8_t numSamples, uint16_t jiffies)

Configures the ADC for sampling a channel multiple times repeatedly. Any previous configuration will be overwritten. In contrast to the configureSingleRepeat() command this configuration means that an event with numSamples conversion results will be signalled, where 0 < numSamples <= 16. In contrast to the configureMultiple() command, this configuration means that numSamples conversion results will be signalled repeatedly until the client returns FAIL in the multipleDataReady() event handler. If configureMultipleRepeat() returns SUCCESS calling getData() will start the the first conversion immediately. The sampling period is specified by the jiffies parameter, which defines the time between successive conversions in terms of clock ticks of clock source "sampcon_ssel" and clock input divider "sampcon_id" as specified in the config parameter. If jiffies is zero successive conversions are performed as quickly as possible. After numSamples conversions an event multipleDataReady() is signalled with numSamples conversion results. If the client returns SUCCESS in the multipleDataReady() event handler, numSamples new conversions will be performed, otherwise not.

Parameters:: config - ADC12 configuration data.; jiffies - Sampling period in terms of clock ticks of "sampcon_ssel" and input divider "sampcon_id".; buffer - The user-allocated buffer in which the conversion results will be stored. It must have at least numSamples entries, i.e. it must have a size of at least numSamples * 2 byte.; numSamples - Number of adc samples to take, 0 < numSamples <= 16
Returns:: SUCCESS means that the ADC was configured successfully and getData() can be called to start with the first conversion.

configureSingle

command error_t configureSingle(msp430adc12_channel_config_t *config)

Configures the ADC to perform a single conversion. Any previous configuration will be overwritten. If SUCCESS is returned calling getData() will start the conversion immediately and a singleDataReady() event will be signalled with the conversion result when the conversion has finished.

Parameters:: config - ADC12 configuration data.
Returns:: SUCCESS means that the ADC was configured successfully and getData() can be called to start the conversion.

configureSingleRepeat

command error_t configureSingleRepeat(msp430adc12_channel_config_t *config, uint16_t jiffies)

Configures the ADC for repeated single channel conversion mode. Any previous configuration will be overwritten. If SUCCESS is returned calling getData() will start sampling the adc channel periodically (the first conversion is started immediately). The sampling period is specified by the jiffies parameter, which defines the time between successive conversions in terms of clock ticks of clock source "sampcon_ssel" and clock input divider "sampcon_id" as specified in the config parameter. If jiffies is zero successive conversions are performed as quickly as possible. Conversion result are signalled until the client returns FAIL in the singleDataReady() event handler.

Parameters:: config - ADC12 configuration data.; jiffies - Sampling period in terms of clock ticks of "sampcon_ssel" and input divider "sampcon_id".
Returns:: SUCCESS means that the ADC was configured successfully and getData() can be called to start with the first conversion.

getData

command error_t getData()

Starts sampling an adc channel using the configuration as specified by the last call to any of the four available configuration commands.

Returns:: SUCCESS means that the conversion was started successfully and an event singleDataReady() or multipleDataReady() will be signalled (depending on the previous configuration). Otherwise no such event will be signalled.

Events - Details

multipleDataReady

event uint16_t *multipleDataReady(uint16_t *buffer, uint16_t numSamples)

Multiple ADC conversion results are ready. If the ADC was configured with the configureMultiple() command, then the return value is ignored. If the ADC was configured with the configureMultipleRepeat() command then the returned pointer defines where to store the next numSamples conversion results (the client must make sure that the buffer is big enough!). Returning a null pointer means that the repeated conversion mode will be stopped.

Parameters:: buffer - Conversion results (lower 12 bit are valid, respectively).; numSamples - Number of samples stored in buffer
Returns:: A null pointer stops a repeated conversion mode. Any non-zero value is interpreted as the next buffer, which must have at least numSamples entries. The return value is ignored if the ADC was configured with configureMultiple().

singleDataReady

event error_t singleDataReady(uint16_t data)

A single ADC conversion result is ready. If the ADC was configured with the configureSingle() command, then the return value is ignored. If the ADC was configured with the configureSingleRepeat() command then the return value tells whether another conversion should be performed (SUCCESS()) or not (FAIL).

Parameters:: data - Conversion result (lower 12 bit).
Returns:: If this event is signalled as response to a call to configureSingleRepeat() then SUCCESS results in another sampling and FAIL stops the repeated sampling. Otherwise the return value is ignored.