Scaling for analog reads

MozziGuts.h

@@ -136,7 +136,15 @@ are called.
 */
 void audioHook();
 
+/** @ingroup analog
+
+See getAudioInput(). The template parameter specifies the desired value range in bits. */
+template<byte RES> uint16_t getAudioInput();
+
+/** @ingroup analog
 
+See getAudioInput(). Equivalent to getAudioInput<16>(). */
+template<byte RES> inline uint16_t getAudioInput16() { return getAudioInput<16>(); }
 
 /** @ingroup analog
 This returns audio input from the input buffer, if
@@ -150,10 +158,19 @@ and
 http://interface.khm.de/index.php/lab/experiments/arduino-realtime-audio-processing/ .
 A circuit and instructions for amplifying and biasing a microphone signal can be found at
 http://www.instructables.com/id/Arduino-Audio-Input/?ALLSTEPS
+
+@note The value range returned by this function follows the same rules as detailed in the documentation
+      for mozziAnalogRead(): For portable code, define MOZZI_ANALGO_READ_RESOLUTION at the top of your
+      sketch, or use the templated version of this function.
+
 @return audio data from the input buffer
 */
-#if !MOZZI_IS(MOZZI_AUDIO_INPUT, MOZZI_AUDIO_INPUT_NONE)
-int getAudioInput();
+#if defined(FOR_DOXYGEN_ONLY) || (!MOZZI_IS(MOZZI_AUDIO_INPUT, MOZZI_AUDIO_INPUT_NONE))
+#if defined(FOR_DOXYGEN_ONLY) || defined(MOZZI_ANALOG_READ_RESOLUTION)
+inline uint16_t getAudioInput() { return getAudioInput<MOZZI_ANALOG_READ_RESOLUTION>(); };
+#else
+MOZZI_DEPRECATED("2.0", "This use of getAudioInput() is not portable. Refer to the API documentation for suggested alternatives") inline uint16_t getAudioInput() { return getAudioInput<MOZZI__INTERNAL_ANALOG_READ_RESOLUTION>(); };
+#endif
 #endif
 
 

examples/02.Control/Control_Echo_Theremin/Control_Echo_Theremin.ino

@@ -57,7 +57,7 @@ void setup(){
 
 
 void updateControl(){
-  int bumpy_input = mozziAnalogRead(INPUT_PIN);
+  int bumpy_input = mozziAnalogRead<10>(INPUT_PIN); // request reading at 10-bit resolution, i.e. 0-1023
   averaged = kAverage.next(bumpy_input);
   aSin0.setFreq(averaged);
   aSin1.setFreq(kDelay.next(averaged));

examples/03.Sensors/Knob_LDR_x2_WavePacket/Knob_LDR_x2_WavePacket.ino

@@ -37,6 +37,8 @@
   Tim Barrass 2013, CC by-nc-sa.
 */
 
+#define MOZZI_ANALOG_READ_RESOLUTION 10 // code below assumes readings to be in the classic 10-bit (0-1023) range
+#include <Mozzi.h>
 #include <WavePacket.h>
 #include <RollingAverage.h>
 #include <AutoMap.h>

examples/03.Sensors/Knob_LightLevel_FMsynth/Knob_LightLevel_FMsynth.ino

@@ -68,7 +68,7 @@ void setup(){
 
 void updateControl(){
   // read the knob
-  int knob_value = mozziAnalogRead(KNOB_PIN); // value is 0-1023
+  int knob_value = mozziAnalogRead<10>(KNOB_PIN); // value is 0-1023
 
   // map the knob to carrier frequency
   int carrier_freq = kMapCarrierFreq(knob_value);
@@ -81,7 +81,7 @@ void updateControl(){
   aModulator.setFreq(mod_freq);
 
   // read the light dependent resistor on the Analog input pin
-  int light_level= mozziAnalogRead(LDR_PIN); // value is 0-1023
+  int light_level= mozziAnalogRead<10>(LDR_PIN); // value is 0-1023
 
   // print the value to the Serial monitor for debugging
   Serial.print("light_level = ");

examples/03.Sensors/Knob_LightLevel_x2_FMsynth/Knob_LightLevel_x2_FMsynth.ino

@@ -36,6 +36,7 @@
   Tim Barrass 2013, CC by-nc-sa.
 */
 
+#define MOZZI_ANALOG_READ_RESOLUTION 10 // code below assumes readings to be in the classic 10-bit (0-1023) range
 #include <Mozzi.h>
 #include <Oscil.h> // oscillator
 #include <tables/cos2048_int8.h> // table for Oscils to play

examples/03.Sensors/Light_Temperature_Detuned/Light_Temperature_Detuned.ino

@@ -102,8 +102,8 @@ void loop(){
 
 void updateControl(){
   // read analog inputs
-  int temperature = mozziAnalogRead(THERMISTOR_PIN); // not calibrated to degrees!
-  int light_input = mozziAnalogRead(LDR_PIN);
+  int temperature = mozziAnalogRead<10>(THERMISTOR_PIN); // not calibrated to degrees! Simply a 10-bit voltage reading (0-1023)
+  int light_input = mozziAnalogRead<10>(LDR_PIN);
 
   float base_freq_offset = OFFSET_SCALE*temperature;
   float divergence = DIVERGENCE_SCALE*light_input;

examples/03.Sensors/Light_Temperature_Multi_Oscil/Light_Temperature_Multi_Oscil.ino

@@ -94,8 +94,8 @@ void updateControl(){
   static float previous_pulse_freq;
 
   // read analog inputs
-  int temperature = mozziAnalogRead(THERMISTOR_PIN); // not calibrated to degrees!
-  int light = mozziAnalogRead(LDR_PIN);
+  int temperature = mozziAnalogRead<10>(THERMISTOR_PIN); // not calibrated to degrees!
+  int light = mozziAnalogRead<10>(LDR_PIN);
 
   // map light reading to volume pulse frequency
   float pulse_freq = (float)light/256;

examples/03.Sensors/Piezo_Frequency/Piezo_Frequency.ino

@@ -47,16 +47,16 @@ void setup(){
 
 
 void updateControl(){
-  // read the piezo
+  // read the piezo. We request 12-bits resolution, here, for values of 0-4095. Some boards
+  // will actually provide that much accuracy, for others the readings are simply shifted to a
+  // larger range.
   int piezo_value = mozziAnalogRead(PIEZO_PIN); // value is 0-1023
 
   // print the value to the Serial monitor for debugging
   Serial.print("piezo_value = ");
   Serial.print(piezo_value);
   Serial.print("\t \t"); // prints 2 tabs
 
-  int frequency = piezo_value*3; // calibrate
-
   // print the frequency to the Serial monitor for debugging
   Serial.print("frequency = ");
   Serial.print(frequency);

examples/03.Sensors/Piezo_SampleScrubber/Piezo_SampleScrubber.ino

@@ -59,7 +59,7 @@ void setup(){
 void updateControl(){
 
   // read the pot
-  int sensor_value = mozziAnalogRead(INPUT_PIN); // value is 0-1023
+  int sensor_value = mozziAnalogRead<10>(INPUT_PIN); // value is 0-1023
 
   // map it to an 8 bit range for efficient calculations in updateAudio
   int target = ((long) sensor_value * BLAHBLAH4B_NUM_CELLS) >> 10; // >> 10 is / 1024

examples/03.Sensors/Piezo_SampleTrigger/Piezo_SampleTrigger.ino

@@ -55,7 +55,7 @@ void setup(){
 
 void updateControl(){
   // read the knob
-  int knob_value = mozziAnalogRead(KNOB_PIN); // value is 0-1023
+  int knob_value = mozziAnalogRead<10>(KNOB_PIN); // value is 0-1023
 
   // map it to values between 0.1 and about double the recorded pitch
   float pitch = (recorded_pitch * (float) knob_value / 512.f) + 0.1f;
@@ -64,7 +64,7 @@ void updateControl(){
   aSample.setFreq(pitch);
 
   // read the piezo
-  int piezo_value = mozziAnalogRead(PIEZO_PIN); // value is 0-1023
+  int piezo_value = mozziAnalogRead<10>(PIEZO_PIN); // value is 0-1023
 
   // print the value to the Serial monitor for debugging
   Serial.print("piezo value = ");

examples/03.Sensors/Piezo_Switch_Pitch/Piezo_Switch_Pitch.ino

@@ -79,7 +79,7 @@ void buttonChangePitch(){
 
 void updateControl(){
   // read the piezo
-  int piezo_value = mozziAnalogRead(PIEZO_PIN); // value is 0-1023
+  int piezo_value = mozziAnalogRead<10>(PIEZO_PIN); // value is 0-1023
 
   // print the value to the Serial monitor for debugging
   Serial.print("piezo value = ");

examples/03.Sensors/Volume_Knob/Volume_Knob.ino

@@ -53,11 +53,9 @@ void setup(){
 
 
 void updateControl(){
-  // read the variable resistor for volume
-  int sensor_value = mozziAnalogRead(INPUT_PIN); // value is 0-1023
-
-  // map it to an 8 bit range for efficient calculations in updateAudio
-  volume = map(sensor_value, 0, 1023, 0, 255);
+  // read the variable resistor for volume. We specifically request only 8 bits of resolution, here, which
+  // is less than the default on most platforms, but a convenient range to work with, where accuracy is not too important.
+  volume = mozziAnalogRead<8>(INPUT_PIN);
 
   // print the value to the Serial monitor for debugging
   Serial.print("volume = ");

examples/03.Sensors/Volume_Knob_LightLevel_Frequency/Volume_Knob_LightLevel_Frequency.ino

@@ -56,19 +56,16 @@ void setup(){
 
 
 void updateControl(){
-  // read the potentiometer
-  int knob_value = mozziAnalogRead(KNOB_PIN); // value is 0-1023
-
-  // map it to an 8 bit volume range for efficient calculations in updateAudio
-  volume = knob_value >> 2;  // 10 bits (0->1023) shifted right by 2 bits to give 8 bits (0->255)
+  // read the potentiometer as only 8 bit volume range for efficient calculations in updateAudio
+  volume = mozziAnalogRead<8>(KNOB_PIN); // value is 0-255
 
   // print the value to the Serial monitor for debugging
   Serial.print("volume = ");
   Serial.print((int)volume);
   Serial.print("\t"); // prints a tab
 
   // read the light dependent resistor
-  int light_level = mozziAnalogRead(LDR_PIN); // value is 0-1023
+  int light_level = mozziAnalogRead<10>(LDR_PIN); // We request 10 bits, here, however. Value is 0-1023
 
   // print the value to the Serial monitor for debugging
   Serial.print("light level = ");

examples/04.Audio_Input/Audio_Input_with_Knob_Filter/Audio_Input_with_Knob_Filter.ino

@@ -44,8 +44,7 @@ void setup(){
 
 
 void updateControl(){
-  int knob = mozziAnalogRead(KNOB_PIN);
-  byte cutoff_freq = knob>>2; // range 0-255
+  byte cutoff_freq = mozziAnalogRead<8>(KNOB_PIN); // range 0-255
   lpf.setCutoffFreq(cutoff_freq);
 }
 

examples/04.Audio_Input/Audio_and_Control_Input/Audio_and_Control_Input.ino

@@ -44,7 +44,7 @@ void setup() {
 
 void updateControl(){
   for (int i=1;i<NUM_ANALOG_INPUTS;i++) { // analog 0 is configured for audio
-    Serial.print(mozziAnalogRead(i)); // mozziAnalogRead is better than analogRead
+    Serial.print(mozziAnalogRead16(i)); // mozziAnalogRead is better than analogRead
     Serial.print("\t"); // tab
   }
   Serial.println();

examples/05.Control_Filters/DCfilter/DCfilter.ino

@@ -32,8 +32,8 @@ void setup() {
 
 
 void updateControl(){
-  // read the value from the sensor:
-  int sensorValue = mozziAnalogRead(sensorPin);
+  // read the value from the sensor in 10 bit resolution:
+  int sensorValue = mozziAnalogRead<10>(sensorPin);
   Serial.print(sensorValue);
   Serial.print("  Filtered = ");
   Serial.println(dcFiltered.next(sensorValue));

examples/05.Control_Filters/Line_vs_Smooth/Line_vs_Smooth.ino

@@ -69,9 +69,9 @@ void setup(){
 volatile unsigned int freq1;  // global so it can be used in updateAudio, volatile to stop it getting changed while being used
 
 void updateControl(){
-  Q16n16 freq0 = Q16n0_to_Q16n16(mozziAnalogRead(0)); // 0 to 1023, scaled up to Q16n16 format
-  freq1 = (unsigned int) mozziAnalogRead(1); // 0 to 1023
-   aInterpolate.set(freq0, AUDIO_STEPS_PER_CONTROL);
+  Q16n16 freq0 = Q16n0_to_Q16n16(mozziAnalogRead<10>(0)); // 0 to 1023, scaled up to Q16n16 format
+  freq1 = (unsigned int) mozziAnalogRead<10>(1); // 0 to 1023
+  aInterpolate.set(freq0, AUDIO_STEPS_PER_CONTROL);
 }
 
 

examples/05.Control_Filters/RollingAverage/RollingAverage.ino

@@ -42,7 +42,7 @@ void setup(){
 
 
 void updateControl(){
-  int bumpy_input = mozziAnalogRead(INPUT_PIN);
+  int bumpy_input = mozziAnalogRead<10>(INPUT_PIN);
   averaged = kAverage.next(bumpy_input);
 
   Serial.print("bumpy \t");

examples/05.Control_Filters/Thermistor_OverSample/Thermistor_OverSample.ino

@@ -69,7 +69,7 @@ void updateControl(){
   static int counter, old_oversampled;
 
   // read the variable resistor
-  int sensor_value = mozziAnalogRead(INPUT_PIN); // value is 0-1023
+  int sensor_value = mozziAnalogRead<10>(INPUT_PIN); // value is 0-1023
 
   // get the next oversampled sensor value
   int oversampled = overSampler.next(sensor_value);

examples/06.Synthesis/PDresonant/PDresonant.ino

@@ -120,13 +120,13 @@ void updateControl(){
   //MIDI.read();
 
   // analog joystick for controlling speed of modulation: assigned to attack, decay times and sustain level
-  //x_axis = mozziAnalogRead(X);
-  //y_axis = mozziAnalogRead(Y);
+  //x_axis = mozziAnalogRead<10>(X);
+  //y_axis = mozziAnalogRead<10>(Y);
 
   // for testing/demo without external input
   fakeMidiRead();
-  x_axis = 512; //mozziAnalogRead(X);
-  y_axis = 512; // mozziAnalogRead(Y);
+  x_axis = 512; //mozziAnalogRead<10>(X);
+  y_axis = 512; // mozziAnalogRead<10>(Y);
 
   voice.update();
 }

examples/06.Synthesis/WavePacket_Double/WavePacket_Double.ino

@@ -52,9 +52,9 @@ void setup(){
 
 
 void updateControl(){
-  wavey.set(kAverageF.next(mozziAnalogRead(FUNDAMENTAL_PIN))+1,
-    kAverageBw.next(mozziAnalogRead(BANDWIDTH_PIN)),
-    kAverageCf.next(2*mozziAnalogRead(CENTREFREQ_PIN)));
+  wavey.set(kAverageF.next(mozziAnalogRead<10>(FUNDAMENTAL_PIN))+1, // 1-1024
+  kAverageBw.next(mozziAnalogRead<10>(BANDWIDTH_PIN)),  // 0-1023
+  kAverageCf.next(mozziAnalogRead<11>(CENTREFREQ_PIN)));  // 0-2047
 }
 
 

examples/06.Synthesis/WavePacket_Sample/WavePacket_Sample.ino

@@ -60,9 +60,9 @@ void setup(){
 
 
 void updateControl(){
-  int f = kAverageF.next(mozziAnalogRead(FUNDAMENTAL_PIN))+1;
-  int b = kAverageBw.next(mozziAnalogRead(BANDWIDTH_PIN));
-  int cf = kAverageCf.next(2*mozziAnalogRead(CENTREFREQ_PIN));
+  int f = kAverageF.next(mozziAnalogRead<10>(FUNDAMENTAL_PIN))+1;
+  int b = kAverageBw.next(mozziAnalogRead<10>(BANDWIDTH_PIN));
+  int cf = kAverageCf.next(mozziAnalogRead<11>(CENTREFREQ_PIN));
   wavey.set(f, b, cf);
 }
 

examples/06.Synthesis/WavePacket_Single/WavePacket_Single.ino

@@ -53,9 +53,9 @@ void setup(){
 
 
 void updateControl(){
-  wavey.set(kAverageF.next(mozziAnalogRead(FUNDAMENTAL_PIN))+1,
-    kAverageBw.next(mozziAnalogRead(BANDWIDTH_PIN)),
-    kAverageCf.next(2*mozziAnalogRead(CENTREFREQ_PIN)));
+  wavey.set(kAverageF.next(mozziAnalogRead<10>(FUNDAMENTAL_PIN))+1,
+    kAverageBw.next(mozziAnalogRead<10>(BANDWIDTH_PIN)),
+    kAverageCf.next(mozziAnalogRead<11>(CENTREFREQ_PIN)));
 }
 
 

internal/MozziGuts.hpp

@@ -27,6 +27,11 @@ static void advanceADCStep();                       // to be provided by platfor
 static void startSecondADCReadOnCurrentChannel();   // to be provided by platform implementation
 static uint8_t adc_count = 0;                       // needed below
 #endif
+
+// TODO: make this helper public?
+template<byte BITS_IN, byte BITS_OUT, typename T> constexpr T smartShift(T value) {
+    return (BITS_IN > BITS_OUT) ? value >> (BITS_IN - BITS_OUT) : (BITS_IN < BITS_OUT) ? value << (BITS_OUT - BITS_IN) : value;
+}
 }
 
 // Include the appropriate implementation
@@ -126,20 +131,20 @@ __attribute__((noinline)) void adcStartReadCycle() {
 	}
 }
 
-int mozziAnalogRead(uint8_t pin) {
+uint16_t mozziAnalogRead(uint8_t pin) {
 	pin = adcPinToChannelNum(pin); // allow for channel or pin numbers; on most platforms other than AVR this has no effect. See note on pins/channels
 	adc_channels_to_read.push(pin);
 	return analog_readings[channelNumToIndex(pin)];
 }
 
 #if !MOZZI_IS(MOZZI_AUDIO_INPUT, MOZZI_AUDIO_INPUT_NONE)
-static AudioOutputStorage_t audio_input; // holds the latest audio from input_buffer
-AudioOutputStorage_t getAudioInput() { return audio_input; }
+static uint16_t audio_input; // holds the latest audio from input_buffer
+uint16_t getAudioInput() { return audio_input; }
 #endif
 
 #if MOZZI_IS(MOZZI__LEGACY_AUDIO_INPUT_IMPL, 1)
 // ring buffer for audio input
-CircularBuffer<unsigned int> input_buffer; // fixed size 256
+CircularBuffer<uint16_t> input_buffer; // fixed size 256
 #define audioInputAvailable() (!input_buffer.isEmpty())
 #define readAudioInput() (input_buffer.read())
 /** NOTE: Triggered at MOZZI_AUDIO_RATE via defaultAudioOutput(). In addition to the AUDIO_INPUT_PIN, at most one reading is taken for mozziAnalogRead().  */
@@ -190,7 +195,7 @@ inline void advanceADCStep() {
 #else
 MOZZI_ASSERT_EQUAL(MOZZI_ANALOG_READ, MOZZI_ANALOG_READ_NONE)
 
-int mozziAnalogRead(uint8_t pin) {
+uint16_t mozziAnalogRead(uint8_t pin) {
   return analogRead(pin);
 }
 
@@ -282,16 +287,17 @@ uint32_t MozziRandPrivate::z=521288629;
 #undef MOZZI__LEGACY_AUDIO_INPUT_IMPL
 
 // "export" publicly accessible functions defined in this file
-// NOTE: unfortunately, we cannot just write using MozziPrivate::mozziMicros(), and that will conflict with, rather than define mozziMicros()
-//       we might want to rethink how this is done. What matters is that these functions are user accessible, though, while most of what we
+// NOTE: unfortunately, we cannot just write "using MozziPrivate::mozziMicros()", etc. as that would conflict with, rather than define mozziMicros().
+//       Instead, for now, we forward the global-scope functions to their implementations inside MozziPrivate.
+//       We might want to rethink how this is done. What matters is that these functions are user accessible, though, while most of what we
 //       now keep in MozziPrivate is hidden away.
-//unsigned long mozziMicros() { return MozziPrivate::mozziMicros(); };
+unsigned long mozziMicros() { return MozziPrivate::mozziMicros(); };
 unsigned long audioTicks() { return MozziPrivate::audioTicks(); };
 void startMozzi(int control_rate_hz) { MozziPrivate::startMozzi(control_rate_hz); };
 void stopMozzi() { MozziPrivate::stopMozzi(); };
-int mozziAnalogRead(uint8_t pin) { return MozziPrivate::mozziAnalogRead(pin); };
+template<byte RES> uint16_t mozziAnalogRead(uint8_t pin) { return MozziPrivate::smartShift<MOZZI__INTERNAL_ANALOG_READ_RESOLUTION, RES>(MozziPrivate::mozziAnalogRead(pin));};
 #if !MOZZI_IS(MOZZI_AUDIO_INPUT, MOZZI_AUDIO_INPUT_NONE)
-AudioOutputStorage_t getAudioInput() { return MozziPrivate::getAudioInput(); };
+template<byte RES> uint16_t getAudioInput() { return MozziPrivate::smartShift<MOZZI__INTERNAL_ANALOG_READ_RESOLUTION, RES>(MozziPrivate::getAudioInput()); };
 #endif
 #if MOZZI_IS(MOZZI_ANALOG_READ, MOZZI_ANALOG_READ_STANDARD)
 void setupMozziADC(int8_t speed) { MozziPrivate::setupMozziADC(speed); };

internal/config_checks_avr.h

@@ -133,6 +133,8 @@
 #define MOZZI_AUDIO_BITS (2*MOZZI_AUDIO_BITS_PER_CHANNEL)
 #endif
 
+#define MOZZI__INTERNAL_ANALOG_READ_RESOLUTION 10
+
 // Step 2: Check
 // NOTE: This step is not technically required, but a good idea in any port