sampler.configure(pins, sampleRate, buffers, callback, filters)

Description

This method configures the sampler. The sampler outputs 16-bit unsigned samples, though with only 12 bits of actual resolution, in the top 12 bits. For example, sampling one pin with a sample rate of 1kHz, 2000 bytes of data are produced every second. With buffers of size 2000 bytes, callback will be called once per second.

If an array of pins is used, all pins are sampled every period. So when sampling three pins at 1kHz, 6000 bytes of data are produced every second. The pins are sampled almost simultaneously. The output data is interleaved: one sample (two bytes) from the first pin, then one sample from the second pin, and so on, then the second sample from the first pin, and so on. Each buffer supplied must be a multiple of two times pinCount bytes: in other words, an even number if sampling just one pin, a multiple of four if sampling two pins, a multiple of 16 if sampling eight pins, or a multiple of 20 if sampling ten pins.

The minimum sample rate is 1/60Hz (0.0166Hz) or one sample per minute; the maximum sample rate of the hardware is a theoretical 2MHz, but Squirrel would be unable to process data at that rate except in short bursts; the maximum achievable sample rate (whether burst or continuous) thus depends on how much further processing is applied, and should be determined empirically for any given application. As a rough guideline, the imp should be able to stream 8kHz 8-bit audio over a network (with network latency being the biggest bottleneck), or calculate a continuous running RMS at 48kHz.

The Sampler Callback

The function passed passed into to the callback parameter is called automatically by the sampler at regular intervals when there is a buffer of data to be processed. It is also called to warn of over-run conditions. The callback function should have the following parameters of its own:

Parameter	Type	Description
buffer	Blob	The samples to be processed
byteCount	Integer	The number of bytes (not samples) valid in the buffer

Buffer Over-runs

An over-run can occur when the processing of the data in the callback takes longer than the sampler takes to fill a buffer. While a buffer is being processed by the callback, it can’t be used by the sampler. When this occurs, buffer is passed null and byteCount is set to 0 when the callback is called, and these values can be used by your code to determine that an over-run has taken place.

It is recommended that you should stop and then restart the sampler after an overrun as this will ensure a consistent state on restart.

Additionally, your application should use the RETURN_ON_ERROR timeout policy as this will ensure that disruptive events, such as WiFi dropouts, do not hinder buffer processing. Indeed, you should not see overruns (provided you have configured the sampler correctly) in these circumstances.

Pre-processing Filters

The pre-processing filters can be used to normalise the samples and perform A-law compression.

Constant	Value	Description
NORMALISE	1	Normalise the data, using an infinite impulse response method with a window size of 256 samples
A_LAW_COMPRESS	2	Compress the data from 16 bit to 8 bit, using A-law compression

The values assigned to the constants may change in a future impOS™ release.

When using the A-law compression option at least three buffers must be used, to avoid over-runs.

The format of the data provided to the callback, depends on the pre-processing filters used:

Pre-processing filters	Output data type
None	Unsigned 16 bit, little-endian
NORMALISE	Signed 16 bit, little-endian
A_LAW_COMPRESS	Signed 8 bit
NORMALISE + A_LAW_COMPRESS	Signed 8 bit

Because the effectiveness of A-law compression is very dependent on the zero-point being in the right place, it’s not usually a good idea to use the A-law compressor without the normalization.

When sampling multiple channels with NORMALISE enabled, all channels are normalized to one single level, not independently per-channel.

Module-specific Information

imp003

While the imp003 has ten ADC-capable pins, it can only sample eight of these at a time.