SimpleTone I2S example, with pins specified

[Andy2No]

The SimpleTone example, for I2S doesn't document which pins are used, so it was necessary to look at the code to work that out. By default, it uses the only three pins that can be analogue inputs, which often wouldn't be what's wanted.

So, here is a very simple change to SimpleTone.ino, which I've verified with an Adafruit UDA1334A based I2S Stereo Decoder, moving the signals to different pins, and adding some comments to explain how to change them.

The I2S.setXXXX() lines must be placed before the I2S.begin().

/*
  This example generates a square wave based tone at a specified frequency
  and sample rate. Then outputs the data using the I2S interface to a
  MAX08357 I2S Amp Breakout board.

  created 17 November 2016
  by Sandeep Mistry
  modified for ESP8266 by Earle F. Philhower, III <earlephilhower@yahoo.com>


Only 16 bitsPerSample are allowed by the PIO code.  Only write, no read.

    bool setBCLK(pin_size_t pin);	// Must be 28 or less.  Default is 26
	// This assigns two adjacent pins - the pin after this one (one greater) is the WS (word select) signal, 
	// which toggles before the sample for each channel is sent

    bool setDOUT(pin_size_t pin);	// Must be 29 or less.  Default is 28


*/

#include <I2S.h>

// GPIO pin numbers

//define pBCLK 26
#define pBCLK 20
#define pWS (pBCLK+1)
//define pDOUT 28
#define pDOUT 22

const int frequency = 440; // frequency of square wave in Hz
const int amplitude = 500; // amplitude of square wave
//const int sampleRate = 8000; // sample rate in Hz
const int sampleRate = 16000; // minimum for UDA1334A

const int halfWavelength = (sampleRate / frequency); // half wavelength of square wave

short sample = amplitude; // current sample value
int count = 0;


void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
  digitalWrite(LED_BUILTIN, 1);
  
  Serial.begin(9600);
  Serial.println("I2S simple tone");

  I2S.setBCLK(pBCLK);  // Must be 28 or less.  Default is 26
  // This assigns two adjacent pins - the pin after this one (one greater) is the WS (word select) signal, 
  // which toggles before the sample for each channel is sent

  I2S.setDOUT(pDOUT); // Must be 29 or less.  Default is 28

  // start I2S at the sample rate with 16-bits per sample
  if (!I2S.begin(sampleRate)) {
    Serial.println("Failed to initialize I2S!");
    while (1); // do nothing
   }

}

void loop() {
  if (count % halfWavelength == 0) {
    // invert the sample every half wavelength count multiple to generate square wave
    sample = -1 * sample;
  }

  // write the same sample twice, once for left and once for the right channel
  I2S.write(sample);
  I2S.write(sample);

  // increment the counter for the next sample
  count++;
}

[earlephilhower]

@Andy2No why not submit a PR with your updated example?

[Andy2No]

@earlephilhower Mostly, because I have no idea how :)

I've stuck to just being a consumer and beta tester, of github repositories. I suppose I ought to learn more about it, but I don't really know where to start.

[earlephilhower]

BTW, good first PR, @Andy2No ! :)

[Andy2No]

Thanks, @earlephilhower :)

[gabrieldeampli]

I'm using a TDA1543. my program processes the signal in real time and generates a sample exactly every 40 microseconds (25KHz). I need to send that sample to the left channel (because it's mono) every time I calculate a new one, but don't waste any processing time in sending it. For now, to accomplish that, I'm dedicating the second core to make the submission to the DAC. Could I do the same with this library and leave the second core free? how?

[earlephilhower]

Are you bit-banging I2S on the 2nd core? If so, the I2S peripheral can do that for you with a PIO state machine and no CPU core use. It also supports "Japanese" mode which might be needed on that primordial chip, see the docs. For mono just write a 0 for one channel, of course.

[gabrieldeampli]

Then I should type
I2S.write(sample);
I2S.write(0):
in my routine.
Time is controlled by my program, right? when running I2S.write() the channel selection bit and data are written, while my program continues to do other things?
in the example made by Andy2No, I don't see waiting between samples. Shouldn't that have problems in the i2S buffer? I believe that running a loop cycle is much faster than it takes to send the data to the i2S bus. Is that program working well?

[Andy2No]

@gabrieldeampli I only added some comments to it, but as I understand it, I2S.write() is a blocking operation so it doesn't return until it's completed. That's responsible for the bulk of the timing.

I suspect that it gets delayed by interrupts, e.g. to update the millis() timer and handle USB, but I haven't checked with recent versions. It's a good enough example to see things are working but for any practical use, the method using buffers is probably the way to go.

[gabrieldeampli]

In that case I cannot use it for my purpose.
But I don't think it works that way. There is no point in using PIOs if they are going to block the program until the data has been sent.

[earlephilhower]

The I2S and all the audio outputs have a queue they transmit from using DMA. The app doesn't block until you actually go so fast you overflow the fifo and need to wait for space to appear. You can use the non-blocking versions of write to see if you're too fast and drop a sample, or the availableForWrite call to guarantee there's enough space before writing.

[gabrieldeampli]

Thank you.
So how could I type that non-blocking command?
Then I could set a samplerate of 44kHz for the I2S and then send an I2S.write() command at 25KHz and, on the one hand, it wouldn't crash my program and, on the other hand, it wouldn't fill the I2S buffers.

[earlephilhower]

Err, it's not going to interpolate samples so you'll be sending 25KHz audio out at 44.1KHz and getting pitch shifting and underflow periods. I'd set them both to the same rate and then add or subtract a sample when there's some jitter if you want to be fancy.

See the I2S docs and the 32-bit write with an async param.

But if you check the availableForWrite results you are guaranteed to know beforehand, anyway, and will never block as long as you don't write more than reported space. The BTAudio samples do this to bulk up writes and reduce CPU overhead.

[gabrieldeampli]

Ah. I think I understand. The writing to the external device via I2S is done at specific times in a synchronous way, so I can't decide exactly when to send my sample. Even if the buffer is empty and I put a sample in it, it is not certain that it will be sent at that moment, but will wait for its turn to be sent. Is that so?
In my program, sending is asynchronous. I have a timer that raises a flag periodically (@25KHz). The loops of both cores wait for that flag to rise, when that happens, one of them calculates the value of a global variable "OUT_TO_DAC", the other core takes the value of that same variable (result of the previous calculation) and starts a new transmission.
I know it's an inelegant way, but with that I get the transmissions to be just every 1/25000 second and the latency of the set is only a sample.
from what you're saying, I think it might be useful for me to read the I2S documents, the asynchronous sending part.
Thank you very much for your help Earle!