Configures the ADC for use
Not available on the imp004m or imp005
|pins||imp pin object or array of pin objects||
Any pin which supports ADC/analog in, or an array of such pins
|sampleRate||Float or integer||
The frequency at which the sampler is set in Hertz
|buffers||Array of blobs||
Up to eight buffers, each a store for sampled data. The size of each blob must be a multiple of twice the number of supplied pins
A function to be called when a sample buffer is full
Optional pre-processing filters (see below)
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 all eight analog-capable pins (on imp002 modules), or a multiple of 20 if sampling all ten analog-capable pins (imp003 modules).
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 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:
|buffer||Blob||The samples to be processed|
|byteCount||Integer||The number of bytes (not samples) valid in the buffer|
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.
The pre-processing filters can be used to normalise the samples and perform A-law compression.
||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.
While the imp003 has ten ADC-capable pins, as of impOS 38 it can only sample eight of these at a time. This is expected to be fixed in a future impOS release.
The following two examples sample at 1kHz for four seconds. The buffers will contain 16-bit, little-endian, unsigned samples. In the first example, a single pin, 2, is used for sampling. In the second, three pins — 2, 5 and 7 — are used.
Sample pin 5 (imp001 or imp002) at 8kHz and A-law compress the data, for a period of four seconds. The buffers will contain 8-bit A-law data.