I’ve recently embarked on a journey to create a digital effects unit (like a guitar pedal, but not a guitar pedal).

It’s been incredibly interesting so far, learning a lot about various different topics, which is as frustrating as it’s rewarding (ok, maybe a bit more rewarding).
What I present here may seem straightforward for some, but it was quite a laborous endeavour packed with trial and error and scarce online resources.

This post aims to share some knowledge about what I’ve learned, for my future self and for anyone else struggling with this too!

The bird’s eye view is this:

                                ┌────────────┐┌────────────┐
                                │  Jack In   ││  Jack Out  │
                                └────────────┘└────────────┘
                                    │             ▲
                                    │             │
                               ┌────┘             └────┐
                               │  ┌─────────────────┐  │
                               └─▶│      CODEC      │──┘
                                  └─────────────────┘
                                           ▲
                                           │
                                           ▼
                                   ┌─────────────────┐
                                   │       MCU       │
                                   └─────────────────┘

MCU selection

Since this project aims to be a real-time audio effects unit, we need something with good speed (to run the effects algorithms, plural) and decent RAM (some algorithms may operate over a group of samples), I decided to go with the STM32H753ZI.

Keys specs being:

• 480MHz
• Double Precision Floating Point Unit (FPU)
• 2MB Flash / 1MB RAM
• An LQFP package (easier to solder than QFN or BGA)

This is maybe overkill for my needs, this is something I can downsize down the line.

And another big deciding factor is that STMicroelectronics provides a devkit for this chip, with the Nucleo-H753 which is incredibly useful to start prototyping without worrying about the MCU circuitry (which will come at a later stage).

The Nucleo dev-boards also come with a builtin STLink which is used for flashing the chip and debugging.

STMicroelectronics provides a nice (and free) all-in-one IDE to work and debug their chips, CubeIDE.
The following assumes you are somewhat familiar with the setup of a basic project, if not Digikey as a great video series on the this topic.

CODEC chip selection

ADC primer

My requirements for the ADC/DAC is 24 of bit depth and 48KHz sampling rate minimum.

24 bits means that the resolution of the ADC for example is represented as a signed integer (so from -2^23 to +2^23, the most significant bit being used for the sign); sampling an analog signal (continous by nature) to discrete values.
The bigger the range of values used to represent this continuous signal, the higher the fidelity.
An extreme example would be a 2 bit ADC (from -1 to +1), where you would only be able to represent “sound” and “no sound”.

And 48KHz is the frequency at which we’re sampling those 24 bits, see the wikipedia article on the Nyquist–Shannon sampling theorem for more information (44.1 is just a weird number…).

If you wish to dive deeper into this topic, xiph.org’s has a great video series going into details I never could.

Sparkfun <3

Again to get up and running as quickly as possible I looked for a chip with an existing breakout board and my research led to Sparkfun’s WM8960 breakout.

The huge plus is that Sparkfun has graciously blessed us with an Arduino library and extensive documentation, which proved invaluable to understand this chip.

Unfortunately this chip has reach the end of its product lifecycle and is now NRND, and none of the suggested replacement ICs have an affordable dev board.

The end goal being to create a custom PCB with all this, I will have to find a new codec.

Still a great choice as a learning tool.

MCU <> Codec Setup

By default the WM8960 is in its “off” state, it won’t power up any of its internals and won’t emit any sound.

To configure it wee need I²C (Inter-Integrated Circuit), which is a nice and simple protocol that allows chips to talk to each other at relatively slow speeds, so it’s perfect for just setting up an IC.

I²C and the WM8960

MCU Configuration

We will need I²C to configure the codec, setting this up in CubeIDE is pretty simple.

These are my settings which are all the defaults. I’m using I2C1.

And these are the pins settings, also default.

WM8960 Configuration

I²C - Reading The Fantastic Manual

This proved particularly tricky and I spent a pretty huge amount of time trying to figure out what I had done wrong.

Well as it’s often the case, I hadn’t RTFM hard enough.

I had assumed that I²C communication is always following this data structure (from the master’s perspective, thus I’ll be ignoring the ACKs from the slave):

• Master writes the 7 bit address of the slave it wishes to address
• The 8th bit is the Read/Write bit
• Master writes the 8 bit register address it whishes to write to
• Master writes another 8 bit of data to be saved to that register

But I assumed wrong, the wikipedia article tells us:

Pure I2C systems support arbitrary message structures.

The only thing the specification stipulates, is that an ACK should be sent every 8 bits.

Here is an excerpt from the the datasheet(page 63):

The WM8960 is controlled by writing to registers through a 2-wire serial control interface. A control word consists of 16 bits. The first 7 bits (B15 to B9) are address bits that select which control register is accessed. The remaining 9 bits (B8 to B0) are data bits, corresponding to the 9 bits in each control register.

In case that wasn’t clear (wasn’t for me at first), all the register addresses in the WM89600 are actually only 7 bits, the 8th bit should be the Most Significant Bit (MSB) of the data you wish to write, which is 9 bits long (instead of the typical 8).

This makes is really hard to debug using a logic analyzer because the data that will be interpreted by your logic analyzer software will not make much sense when trying to compare it with the datasheet.

For instance, if you want to write 0x008 to the register 0x29.
You need to left shift by one the register address and jam your data’s MSB in its place: (0x29 << 1) | (0x008 >> 8); and the of course omit your the MSB you just added to the address from your data… (casting from uint_16 to uint_8 and bit masking does the trick).

Which is very confusing because the register you wanted to address (say 0x29 for example) is now left shifted once (so 0x58)… And your data also won’t look like what you expect because it will be missing it’s MSB…
It’s messy, and I don’t think it’s very common… But that’s how this codec works.

Clock settings

I had a weird issue at first where after a random amount of time, the sound would sharply degrade over the course of a few seconds all the way down to just noise.
Took me a while to figure out, in the end the issue turned out to be clock related, my guess is that since the configuration was inacurrate, after some time a desync would occur preventing proper function.

There are a few different clocks used in the codec, the main ones which are driving pretty much everything else are SYSCLK and MCLK.

On the Sparkfun board, MCLK cannot be changed as it’s provided by the 24MHz crystal oscillator soldered on the board and connected to pin 11 of the codec chip.

SYSCLK can be provided externally or derived from MCLK, the latter is what we’ll be using.

We also want a 48KHz sample rate, the datasheet tells us that we need a SYSCLK of 12.288 MHz.

SYSCLK can be generated by a Phased-Locked Loop, (aka PLL) that uses MCLK as its input, the following table gives us the values we need to use:

And this is achieved via the following snippet (full code available later in this article).

More information on these registers and values can be found on pages 59 and 60 of the datasheet for the codec.

...
  ret += _writeRegister(hi2c, 0x34, 0b000111000);
  ret += _writeRegister(hi2c, 0x35, 0x31);
  ret += _writeRegister(hi2c, 0x36, 0x26);
  ret += _writeRegister(hi2c, 0x37, 0xe8);
...

Code

In this configuration the Codec will only route the input audio from R/LINPUT2 to the ADC and then out the DAC to the headphone output.

The DAC and ADC word select lines are shared via the DLRC pin, do not use the ALRC pin as it’s configured as an output GPIO.

There may be some other things I’m missing… In any case this code can help but will likely not spare you a full read of the datasheet.

I’ve uploaded the full code in a public gist.

/*
 * wm8960.c
 *
 * Date: 2024-09-03
 * Author: @pyrho
 */

#include "wm8960.h"
#include "stm32h7xx_hal_def.h"
#include "stm32h7xx_hal_i2c.h"

static HAL_StatusTypeDef _writeRegister(I2C_HandleTypeDef *hi2c,
                                        uint8_t address, uint16_t data);
// P.63 of datasheet
// 7bit addr + R/W bit, MSB first
// The 7bit address is `0b0011010` the 8th bit is the R/W bit which needs to
// be set to `0` to be able to write.
// So this translates to 0x34 as stated in the datasheet
// Sparkfun uses `0x1A`, because they're using Arduino's "Wire" which I guess
// does the left shift on its own.
#define WM8960_I2C_ADDR 0x34

// Private API {{{
//

static HAL_StatusTypeDef _writeRegister(I2C_HandleTypeDef *hi2c,
                                        uint8_t address, uint16_t data) {

  // Shift the register address left 1 bit to leave room to the 9th
  // bit of the data
  uint16_t address_byte = address << 1;

  // Add the MSbit of the data to write to the register's address
  address_byte |= (data >> 8);

  uint8_t data_without_9th_bit = (0x00FF & data);

  return HAL_I2C_Mem_Write(hi2c, WM8960_I2C_ADDR, address_byte,
                           I2C_MEMADD_SIZE_8BIT, &data_without_9th_bit, 1,
                           HAL_MAX_DELAY);
}

// }}}

// Public API {{{

bool WM8960_isReady(I2C_HandleTypeDef *hi2c) {
  return HAL_I2C_IsDeviceReady(hi2c, WM8960_I2C_ADDR, 5, 100) == HAL_OK;
}

HAL_StatusTypeDef WM8960_init(I2C_HandleTypeDef *hi2c) {
  /*
   * #Observations
   * This these clock settings, this gives a SYSCLK @ 12.285MHz (close to the
   * reference 12.288)
   */
  HAL_StatusTypeDef ret = 0;

  // Reset
  ret += _writeRegister(hi2c, 0x0f, 0b000000001);

  // IPVU    > 8
  // LINMUTE > 7
  // LIZC    > 6
  // LINVOL  > 5:0
  // This is only for LINPUT1
  // ret += _writeRegister(hi2c, 0x00, 0b101111111);

  // PIVU    > 8
  // RINMUTE > 7
  // RIZC    > 6
  // RINVOL  > 5:0
  // This is only for RINPUT1
  // ret += _writeRegister(hi2c, 0x01, 0b101111111);

  // OUT1VU   > 8   > 1
  // LO1ZC    > 7   > 1
  // LOUT1VOL > 6:0 > 1111111 > = +6dB
  ret += _writeRegister(hi2c, 0x02, 0b111111111);
  ret += _writeRegister(hi2c, 0x02, 0b111111111);

  // OUT1VU   > 8   > 1
  // RO1ZC    > 7   > 1
  // ROUT1VOL > 6:0 > 111111 > = +6dB
  ret += _writeRegister(hi2c, 0x03, 0b111111111);
  ret += _writeRegister(hi2c, 0x03, 0b111111111);

  // Clocks {{{
  // ADCDIV    > 8:6 > 000
  // DACDIV    > 5:3 > 000
  // SYSCLKDIV > 2:1 > 10
  // CLKSEL    > 0   > 1
  ret += _writeRegister(hi2c, 0x04, 0b000000101);

  // OPCLKDIV    > 8:6 > 000  > don't care
  // SDM         > 5   > 1    > Fractional mode, because we need to provide the
  // factional part "K" of the PLL PLLPRESCALE > 4   > 1    > /2, see table P.
  // 61, values for 24MHz PLLN        > 3:0 > 1000 > 8, see table P. 61, values
  // for 24MHz
  ret += _writeRegister(hi2c, 0x34, 0b000111000);

  // 0x3126E8 => 0b 0011 0001 0110 1110 1000
  // 0x3126E8 => 0b 000011 00010110 11101000
  // input 24
  // desired: 12.288
  // prescale 2
  // sysclkdiv 2
  // R: 8.192
  // N: 0x8
  // K: 0x3126E8
  //
  // RES > 8 > 0
  // PLLK > 7:0 >
  ret += _writeRegister(hi2c, 0x35, 0x31);

  // RES > 8 > 0
  // PLLK > 7:0 >
  ret += _writeRegister(hi2c, 0x36, 0x26);

  // RES > 8 > 0
  // PLLK > 7:0 >
  ret += _writeRegister(hi2c, 0x37, 0xe8);

  // RES      > 8:7 > 00
  // ALRCGPIO > 6   > 1  > For debugging the clock
  // WL8      > 5   > 0
  // DACCOMP  > 4:3 > 00
  // ADCCOMP  > 2:1 > 00
  // LOOPBACK > 0   > 0
  ret += _writeRegister(hi2c, 0x09, 0b001000000);

  // }}}

  // Default clock is fine (but maybe not, since the datasheet only mentions a
  // max MCLK frequency of 12.288MHz, but the onboard xtal is 25MHz) According
  // to P.61 this is it. But actually if I want 48Khz, targeting 12.288 is
  // better that 11.2896 So for a 24Mhz crystal, this is better:
  // 24 12.288 98.304 2 2 4 8.192 8h 0x3126E8
  //

  // RES     > 8   > 0
  // DACDIV2 > 7   > 0
  // ADCPOL  > 6:5 > 00
  // RES     > 4   > 0
  // DACMU   > 3   > 0
  // DEEMPH  > 2:1 > 00
  ret += _writeRegister(hi2c, 0x05, 0b000000000);

  // DACVU   > 8   > 1
  // LDACVOL > 7:0 > 1111 1111 > 0dB
  ret += _writeRegister(hi2c, 0x0a, 0b111111111);
  // Doubled for VU
  ret += _writeRegister(hi2c, 0x0a, 0b111111111);

  // DACVU   > 8   > 1
  // RDACVOL > 7:0 > 1111 1111 > 0dB
  ret += _writeRegister(hi2c, 0x0b, 0b111111111);
  // Doubled for VU
  ret += _writeRegister(hi2c, 0x0b, 0b111111111);

  // RES  > 8   > 0
  // NGTH > 7:3 > 00000
  // RES  > 2:1 > 00
  // NGAT > 0   > 0     > Noise gate
  ret += _writeRegister(hi2c, 0x14, 0b00000001);

  // ADCVU   > 8   > 1
  // LADCVOL > 7:0 > 1111 1111 > 0000 0000 = 0db / 1111 1111 = +30dB / 0.5 steps
  // 0b11000011 = 0dB
  ret += _writeRegister(hi2c, 0x15, 0b111000011);
  // Doubled for VU
  ret += _writeRegister(hi2c, 0x15, 0b111000011);

  // ADCVU   > 8   > 1
  // RADCVOL > 7:0 > 1111 1111 > 0000 0000 = 0db / 1111 1111 = +30dB / 0.5 steps
  // 0b11000011 = 0dB
  ret += _writeRegister(hi2c, 0x16, 0b111000011);
  // Doubled for VU
  ret += _writeRegister(hi2c, 0x16, 0b111000011);

  // VMIDSEL > 8:7 > 01
  // VREF    > 6   > 1
  // AINL    > 5   > 1
  // AINR    > 4   > 1
  // ADCL    > 3   > 1
  // ADCR    > 2   > 1
  // MICB    > 1   > 0
  // DIGENB  > 0   > 0
  ret += _writeRegister(hi2c, 0x19, 0b011111100);

  // DACL   > 8 > 1
  // DACR   > 7 > 1
  // LOUT1  > 6 > 1
  // ROUT1  > 5 > 1
  // SPKL   > 4 > 1
  // SPKR   > 3 > 1
  // RES    > 2 > 0
  // OUT3   > 1 > 1
  // PLL_EN > 0 > 1
  ret += _writeRegister(hi2c, 0x1a, 0b111111011);

  // LMN1      > 8   > 0
  // LMP3      > 7   > 0
  // LMP2      > 6   > 0
  // LMICBOOST > 5:4 > 00
  // LMIC2B    > 3   > 0
  // RES       > 2:0 > 000
  ret += _writeRegister(hi2c, 0x20, 0b000000000);

  // RMN1      > 8   > 0
  // RMP3      > 7   > 0
  // RMP2      > 6   > 0
  // RMICBOOST > 5:4 > 00
  // RMIC2B    > 3   > 0
  // RES       > 2:0 > 000
  ret += _writeRegister(hi2c, 0x21, 0b000000000);

  // LD2LO    > 8   > 1
  // LI2LO    > 7   > 0
  // LI2LOVOL > 6:4 > 000
  // RES      > 3:0 > 0000
  ret += _writeRegister(hi2c, 0x22, 0b100000000);

  // RD2LO    > 8   > 1
  // RI2LO    > 7   > 0
  // RI2LOVOL > 6:4 > 000
  // RES      > 3:0 > 0000
  ret += _writeRegister(hi2c, 0x25, 0b100000000);

  // RES       > 8:7 > 00
  // LIN3BOOST > 6:4 > 000
  // LIN2BOOST > 3:1 > 100 > 000 = mute / 001 = -12dB / 111 = +6dB (3dB steps)
  // RES       > 0   > 0
  ret += _writeRegister(hi2c, 0x2B, 0b000001000);

  // RES       > 8:7 > 00
  // RIN3BOOST > 6:4 > 000
  // RIN2BOOST > 3:1 > 100 > 000 = mute / 001 = -12dB / 111 = +6dB (3dB steps)
  // RES       > 0   > 0
  ret += _writeRegister(hi2c, 0x2C, 0b000001000);

  // RES   > 8:6 > 000
  // LMIC  > 5   > 0
  // RMIC  > 4   > 0
  // LOMIX > 3   > 1
  // ROMIX > 2   > 1
  // RES   > 1:0 > 00
  ret += _writeRegister(hi2c, 0x2f, 0b000001100);

  // RES     > 8   > 0
  // GPIOPOL > 7   > 0
  // GPIOSEL > 6:4 > 100 > SYSCLK OUT
  // HPSEL   > 3:2 > 11
  // TSENSEN > 1   > 1
  // MBSEL   > 0   > 0
  ret += _writeRegister(hi2c, 0x30, 0b001001110);

  return ret;
}

// }}}

Inter-Integrated Circuit Sound (I²S)

I²S is a protocol specifically designed to allow chips to exchange audio data.

It’s a 3-wire protocol:

• SD: The stream of audio bits
• WS: Left/Right channel selection, this is the sampling frequency
• CK: The Bit clock

The sample rate is determined by the frequency of the WS signal. At 48KHz/24bits stereo we have 48000 samples per seconds for two channels, and each channel contains 24 bits of data.

MCU Configuration

The STM32 will be communicating via I2S Full Duplex and act as the master. One “simplex” is used to receive data from the ADC, the other to send data to the DAC.

In full duplex there’s an extra “SD” wire to account for the extra communication channel.

Direct Memory Access (DMA)

In order to process the audio in real time, your MCU can’t be polling the ADC to get its data or the audio will be choppy and of poor quality.

This is where DMA comes into play, DMA allows peripherals to access the memory directly bypassing the MCU’s main program.

In our case we’ll setup DMA so that the ADC can write to a circular buffer (circular means the buffer is of fixed size and the ADC will write over previous data in a circular fashion).

DMA also works by providing us with two callbacks, when the buffer is half written and when it’s fully written.
This allows for what’s called a “ping pong” buffer, where we can process the first half of the buffer while the ADC is writing the second half, and so on.

Please checkout Phil’s amazing video for more details on this topic.

Closing Notes

While this setup works and sounds can be heard clearly, I think there might still be an issue somewhere in my setup as the quality of my output signal when viewed on an oscilloscope is very poor and looks like noise; whereas it looks fine when bypassing my setup entirely (so it’s not a measurement issue… I think).

This is a raw-ish dump of my work on this so far so that I can refer to it in the future and hopefully it may help others on this mattter; but keep in mind this is all very “alpha” and ymmv.

Thanks o/

Links

• WM8960 datasheet
• Sparkfun WM8960 guide
• Wikipedia: I²S
• Wikipedia: I²C
• Phil’s Lab I2S/DMA video

Quick post to dump some information on connecting Sparkfun’s WM8960 Audio Codec breakout board to an ESP8266.

But why?

My end goal is to connect this codec to an STM32F4 MCU, but I can’t seem to get it to work yet.
So in order to better understand how this codec chip works and where my mistake is, I decided to walk before I run and tried the examples provided by Sparkfun.

The examples and guide all run on their own “IoT RedBoard ESP32” development board, which I don’t have; however, I do have some cheap ESP8266 boards (NodeMCU V3) ¹ which I will use here (this will most probably work with other ESP chips).

The wiring is different and the code also needed some changes, the examples use the #include <drivers/i2s.h> for I2S but I wasn’t able to find it (surely it must exists somewhere).
I was able to find esp8266/Arduino, which provides an I2S driver.

Wiring

The WM8960 is configured via I2C, and the audio data is sent to the MCU via I2S (Inter-Integrated Circuit Sound).

I2C requires 2 wires:

• SDA (data)
• SCL (clock)

I2S requires 3 wires minimum:

• BCLK (bit clock)
• WS (word select, left/right select)
• SD (data)

The ESP8266 seems to have two IS2 ports, each seem to operate in half duplex. One port is dedicated to receiving and the other for transmitting.
I’ve extracted the pins from reading the source code of the driver.
They are (for this example we’re only receiving data so I’m using port I2SI, I2SO is for transmitting):

• I2S_SD: 12
• I2S_BCK: 13
• I2S_WS: 14

Note that these numbers refer to GPIOXX, where XX is that number.
Example I2S_SD is on GPIO12, which is marked D5 on the PCB.

For reference here is the pinout of the NodeMCU which I’m using:

And finally here is the wiring diagram.
The input voltage from the power supply is 5V, you need this for the codec to work, the 3.3V supplied by the ESP8266 is not enough.

Code

This code is adapted from Sparkfun’s WM8960 arduino library example 11 “Volume Plotter” To run this you will need the Arduino IDE, with the Board Definition for the 8266, which can be found here (this will also contain the I2S driver code).

I’ve modified the original code to work with the 8266, the rest is the same.

#include <I2S.h>
#include <Wire.h>
#include <SparkFun_WM8960_Arduino_Library.h> 

// Click here to get the library: http://librarymanager/All#SparkFun_WM8960
WM8960 codec;
I2SClass* i2sinst;
// Define input buffer length
#define bufferLen 64
int16_t sBuffer[bufferLen];

void setup()
{
  Serial.begin(115200);

  Wire.begin();

  if (codec.begin() == false) //Begin communication over I2C
  {
    Serial.println("The device did not respond. Please check wiring.");
    while (1); // Freeze
  }

   codec_setup();
   i2sinst  = new I2SClass(false, true, true);
   int ret = i2sinst->begin(I2S_PHILIPS_MODE, 44100, 24);
}

void loop()
{

  // False print statements to "lock range" on serial plotter display
  // Change rangelimit value to adjust "sensitivity"
  int rangelimit = 3000;

  // Get I2S data and place in data buffer
  size_t bytesIn = 0;
  int rrr = i2sinst->available();
  bytesIn = i2sinst->read(&sBuffer, bufferLen);
  if (bytesIn > 0)
  {
    int16_t samples_read = bytesIn / 8;
    if (samples_read > 0) {
      float mean = 0;
      for (int16_t i = 0; i < samples_read; ++i) {
        mean += (sBuffer[i]);
      }

      // Average the data reading
      mean /= samples_read;

      // Print to serial plotter
      Serial.println(mean);
    }
  }
}

void codec_setup()
{
  // General setup needed
  codec.enableVREF();
  codec.enableVMID();

  // Setup signal flow to the ADC

  codec.enableLMIC();
  codec.enableRMIC();

  // Connect from INPUT1 to "n" (aka inverting) inputs of PGAs.
  codec.connectLMN1();
  codec.connectRMN1();

  // Disable mutes on PGA inputs (aka INTPUT1)
  codec.disableLINMUTE();
  codec.disableRINMUTE();

  // Set pga volumes
  codec.setLINVOLDB(0.00); // Valid options are -17.25dB to +30dB (0.75dB steps)
  codec.setRINVOLDB(0.00); // Valid options are -17.25dB to +30dB (0.75dB steps)

  // Set input boosts to get inputs 1 to the boost mixers
  codec.setLMICBOOST(WM8960_MIC_BOOST_GAIN_0DB);
  codec.setRMICBOOST(WM8960_MIC_BOOST_GAIN_0DB);

  // Connect from MIC inputs (aka pga output) to boost mixers
  codec.connectLMIC2B();
  codec.connectRMIC2B();

  // Enable boost mixers
  codec.enableAINL();
  codec.enableAINR();

  // Connect LB2LO (booster to output mixer (analog bypass)
  codec.enableLB2LO();
  codec.enableRB2RO();

  // Disconnect from DAC outputs to output mixer
  codec.disableLD2LO();
  codec.disableRD2RO();

  // Set gainstage between booster mixer and output mixer
  codec.setLB2LOVOL(WM8960_OUTPUT_MIXER_GAIN_0DB); 
  codec.setRB2ROVOL(WM8960_OUTPUT_MIXER_GAIN_0DB); 

  // Enable output mixers
  codec.enableLOMIX();
  codec.enableROMIX();

  // CLOCK STUFF, These settings will get you 44.1KHz sample rate, and class-d 
  // freq at 705.6kHz
  codec.enablePLL(); // Needed for class-d amp clock
  codec.setPLLPRESCALE(WM8960_PLLPRESCALE_DIV_2);
  codec.setSMD(WM8960_PLL_MODE_FRACTIONAL);
  codec.setCLKSEL(WM8960_CLKSEL_PLL);
  codec.setSYSCLKDIV(WM8960_SYSCLK_DIV_BY_2);
  codec.setBCLKDIV(4);
  codec.setDCLKDIV(WM8960_DCLKDIV_16);
  codec.setPLLN(7);
  codec.setPLLK(0x86, 0xC2, 0x26); // PLLK=86C226h
  //codec.setADCDIV(0); // Default is 000 (what we need for 44.1KHz)
  //codec.setDACDIV(0); // Default is 000 (what we need for 44.1KHz)
  codec.setWL(WM8960_WL_24BIT);

  codec.enablePeripheralMode();

  // Enable ADCs, and disable DACs
  codec.enableAdcLeft();
  codec.enableAdcRight();
  codec.disableDacLeft();
  codec.disableDacRight();
  codec.disableDacMute();

  codec.disableLoopBack();

  // Default is "soft mute" on, so we must disable mute to make channels active
  codec.enableDacMute(); 

  codec.enableHeadphones();
  codec.enableOUT3MIX(); // Provides VMID as buffer for headphone ground

  codec.setHeadphoneVolumeDB(0.00);
}

Now plug in some form of audio source in the input jack (connected to R/LIN3 on the codec), and if everything went well you should see something like this:

Cheers!

What is Joystick Gremlin?

No point in paraphrasing the perfectly accurate description on their own website.

Joystick Gremlin is a program that allows the configuration of joystick like devices, similar to what CH Control Manager and Thrustmaster’s T.A.R.G.E.T. do for their respectively supported joysticks. However, Joystick Gremlin works with any device be it from different manufacturers or custom devices that appear as a joystick to Windows. Joystick Gremlin uses the virtual joysticks provided by vJoy to map physical to virtual inputs and apply various other transformations such as response curves to analogue axes. In addition to customizing joysticks, Joystick Gremlin also provides powerful macro functionalities, a flexible mode system, scripting using Python, and many other features.

The key points being:

• You don’t need to rely on the usually shitty software provided by the manufacturer
• There is a programmable (python) API
• It’s not tied to one application, so for example you can set your joystick curves once and they’ll be applied in all your games.

In this article I will mostly discuss the Python API, the GUI is well documented on their website; the API… not so much. I’ve struggled quite a bit, navigating github issues for snippets of working code where the documentation failed me. So I thought I would share my experience and hopefully help someone.

All of the code used here is available on Github over here.

Note: this is for Joystick Gremlin version 13.1, from what I saw the API has had a few breaking changes over time so the following may not apply for future releases.

Plugin Setup

The first thing you need to do is to fetch your devices GUIDs. This can be done directly from JG’s GUI under Tools>Device Information.

With that in hand you can now initialize the JoystickDecorator:

my_throttle1 = gremlin.input_devices.JoystickDecorator( \
		# Not sure if the name is important, but I just named
		# it exactly the same as what JG sees
                "Throttle - HOTAS Warthog ", \
		# You should replace this GUID with your own
                "{6EB24530-1896-11EB-8001-444553540000}", \
		# The name of the JG mode
                "Default")

Of course you can have as many as you want. This will allow you to access axises and buttons.

Simple Map

@my_throttle1.button(1)
def callback(event, vjoy, joy):
     vjoy[1].button(1).is_pressed = event.is_pressed

This says: “When Button 1 of my throttle is pressed, Button 1 on the virtual joystick will be pressed too”. The callback is called when the button is pressed and another time upon release. Basically both buttons are in sync.

Creating a virtual third button state

On the Warthog throttle there are two 3 states switches (the flaps and the autopilot mode). Unfortunately the middle state is OFF so no keypress is emitted when it’s in this position.

We can fix this with Joystick Gremlin!

def toggleSwitchMiddle(event, vjoy, joy, otherUp, otherDown, virtualButton):
    if event.is_pressed:
        vjoy[1].button(virtualButton).is_pressed = False
    else:
        j = joy[gremlin.profile.parse_guid(THROTTLE_GUID)]
        bPath = otherUp
        bAlt = otherDown
        if not j.button(bPath).is_pressed and not j.button(bAlt).is_pressed:
            vjoy[1].button(virtualButton).is_pressed = True

@my_throttle1.button(THROTTLE_BUTTONS["AP_PATH"])
def apPath(event, vjoy, joy):
     toggleSwitchMiddle(event, vjoy, joy, THROTTLE_BUTTONS["AP_PATH"], THROTTLE_BUTTONS["AP_ALT"], VJOY_BUTTONS["AP_PITCH_OFF"])

@my_throttle1.button(THROTTLE_BUTTONS["AP_ALT"])
def apAlt(event, vjoy, joy):
    toggleSwitchMiddle(event, vjoy, joy, THROTTLE_BUTTONS["AP_PATH"], THROTTLE_BUTTONS["AP_ALT"], VJOY_BUTTONS["AP_PITCH_OFF"])

Note that this uses the THROTTLE_BUTTONS variable, which is just a map referencing the button numbers by their label on the throttle, helps a bit.

Put simply what this does is simply activate a button on the virtual joystick (our output) if neither the bottom nor the top state of the switch is activated.

Startup Sync

Now since those callbacks are only called when there is a change in button state, they aren’t called when the throttle is turned on.

So if our 3 way switch was in the middle position at that time, the Virtual Joystick output would not be “on” (for that middle state).

We can fix this by calling a little function when Joystick Gremlin starts.

 def sync():
    gremlin.util.log("Initial sync")
    joy_proxy = gremlin.input_devices.JoystickProxy()    
    vjoy_proxy = gremlin.joystick_handling.VJoyProxy()

    # AP 3-way switch inital sync
    apPathIsPressed = joy_proxy[gremlin.profile.parse_guid(THROTTLE_GUID)].button(THROTTLE_BUTTONS["AP_PATH"]).is_pressed
    apAltIsPressed = joy_proxy[gremlin.profile.parse_guid(THROTTLE_GUID)].button(THROTTLE_BUTTONS["AP_ALT"]).is_pressed
    # If it's neither up nor down, switch the vJoy for the middle state on
    vjoy_proxy[1].button(VJOY_BUTTONS["AP_PITCH_OFF"]).is_pressed = (not apPathIsPressed) and (not apAltIsPressed)

sync()

Macros

You can also trigger macros with a press of a joystick button. I’m no python guru, but I think this is a little dirty. But hey, it works.

The following macro is used to turn on various system at once in DCS’s F-16C

First you need to define a macro (this won’t run it):

MACROS = {
    "fcr": macro.Macro(),
} 

# I hate python
## FCR/Radar/Right Hardpoint Macro
MACROS["fcr"].press("leftshift")
MACROS["fcr"].tap("f1")
MACROS["fcr"].pause(0.2)
MACROS["fcr"].tap("f2")
MACROS["fcr"].pause(0.2)
MACROS["fcr"].tap("f3")
MACROS["fcr"].release("leftshift")

Then you can call it like so:

@my_throttle1.button(THROTTLE_BUTTONS["ENG_R"])
def engLeft(event, vjoy):
    if event.is_pressed:
        macro.MacroManager().queue_macro(MACROS["mmc"])

Emulating 3 states on a push button

# Autopilot roll 3-way emulation {{{
AP_ROLL_CYCLE_STATE = 0
"""
This function make the "Enagage/Disengage" button on the throttle act as a three way switch.
Each press will cycle the switch down.
The  ing position is in the middle
Cycle between autopilot ROLL modes.
From sync, this starts in the middle position as ATT_HOLD
"""
@thrt.button(THROTTLE_BUTTONS["AP_ENGAGE_DISENGAGE"])
def apRollCycle(event, vjoy):
    global AP_ROLL_CYCLE_STATE
    if (not event.is_pressed):
        return
        
    if AP_ROLL_CYCLE_STATE == 0:
        vjoy[1].button(VJOY_BUTTONS["AP_ROLL_ATT_HOLD"]).is_pressed = False
        vjoy[1].button(VJOY_BUTTONS["AP_ROLL_STRG_SEL"]).is_pressed = True
        AP_ROLL_CYCLE_STATE = 1
    elif AP_ROLL_CYCLE_STATE == 1:
        vjoy[1].button(VJOY_BUTTONS["AP_ROLL_STRG_SEL"]).is_pressed = False
        vjoy[1].button(VJOY_BUTTONS["AP_ROLL_HDG_SEL"]).is_pressed = True
        AP_ROLL_CYCLE_STATE = 2
    elif AP_ROLL_CYCLE_STATE == 2:
        vjoy[1].button(VJOY_BUTTONS["AP_ROLL_HDG_SEL"]).is_pressed = False
        vjoy[1].button(VJOY_BUTTONS["AP_ROLL_ATT_HOLD"]).is_pressed = True
        AP_ROLL_CYCLE_STATE = 0
# }}}

This makes use of a global variable to store the current state (again this is not top notch programing I know). And cycles through 3 states as the button is pressed.

Using the plugin

Just add your python file in the plugins tab of JG’s UI.

Remarks

• You can use Joystick Gremlin’s UI to figure out the number for each of the buttons
• You can use gremlin.util.log("My message") to debug your scripts, the output will be shown in JG itself in the log window
• You can find the key codes for keyboard keys in JG’s macro.py file

2020-09-10 update: see at the bottom for a better way to create the mappings

Custom text objects ?!

I’ve been using the Vim for ~11 years now (well, neovim really), and somehow I’ve only today realized users can create their own text objects !

If you don’t already know what text objects are, read the man page (:h text-objects), you’re really missing out on Vim’s modal superpowers.

I also won’t bore you with the exact details on how to create your own text objects, Vimways has an excellent article on the subject.

How it got there

Long story short (not), I’m using Tim Pope’s vim-dadbod plugin to interact with my database (another epic plugin by the legend btw), and I have a markdown file with some queries fenced in an SQL code block with some description, literate programing style. I store queries I frequently run, and explain in detais more complex ones.

This setup plays nicely with vim-dadbod because alongside being able to run queries from the vim command line (eg. :DB SELECT id FROM mytable;<CR>) you can also visually select a bunch of lines and call :DB on it.

All my queries are fenced, and was looking for a way to execute the whole block without having to visually and manually select them.

Productivity level: -100

I then set out to find a way to do that, I first found this great blog post about using text objects with dadbod, but it turns out the feature is already baked in dadbod.

Then there is also this issue from 4 years ago about having a text object for code fence blocks in vim-markdown (this is getting to be a pretty deep rabbit hole).

Time for some action.

Markdown Code Fence Text objects !

Just slip this somewhere in your config file and

function! s:inCodeFence()
    " Search backwards for the opening of the code fence.
	call search('^```.*$', 'bceW')
    " Move one line down
	normal! j
    " Move to the begining of the line at start selecting
	normal! 0v
    " Search forward for the closing of the code fence.
	call search("```", 'ceW')

	normal! kg_
endfunction

function! s:aroundCodeFence()
    " Search backwards for the opening of the code fence.
	call search('^```.*$', 'bcW')
	normal! v$
    " Search forward for the closing of the code fence.
	call search('```', 'eW')
endfunction

autocmd Filetype markdown xnoremap <silent> if :<c-u>call <sid>inCodeFence()<cr>
autocmd Filetype markdown onoremap <silent> if :<c-u>call <sid>inCodeFence()<cr>
autocmd Filetype markdown xnoremap <silent> af :<c-u>call <sid>aroundCodeFence()<cr>
autocmd Filetype markdown onoremap <silent> af :<c-u>call <sid>aroundCodeFence()<cr>

Bonus: SQL Queries Text Object

And as a little bonus from this github issue that gives text objects directly for queries ! So you can use that outside of fenced markdown code blocks.

vnoremap aq <esc>:call search(";", "cWz")<cr>:call search(";\\<bar>\\%^", "bsWz")<cr>:call search("\\v\\c^(select<bar>with<bar>insert<bar>update<bar>delete<bar>create)\>", "Wz")<cr>vg`'
omap aq :normal vaq<cr>

Creating a mapping

Now that we have two types of text objects (queries and code fenced blocks), all we need is a mapping to run the queries via vim-dadbod !

Here is mine (my leader key is <Space>):

nmap <expr> <leader>d db#op_exec()
xmap <expr> <leader>d db#op_exec()

And now all you need to do is (in normal mode) <Space>dif to run a query that’s in a fenced code block, and <Space>daq to run a query !

🎉

2020-09-10 Update

As pointed by this kind dude a better way to provide those mappings is to define them as buffer local mappings. And creating an after ftplugin file for markdown is even more idiomatic (my initial autocmd would be run each time the markdown filetype was set).

To quote the VimWays page on mappings:

<buffer> makes the new mapping buffer-local, ie. it will be defined only for the buffer that was current when the mapping was created. It is useful in filetype-specific settings, eg. in ~/.vim/after/ftplugin/help.vim […] A buffer-local mapping […] is created on buffers with the help filetype, ie. help buffers created with :help. […] Obviously, this only makes sense in help buffers, so we should not make this mapping global.

So the updated final version, in ~/.vim/after/ftplugin/markdown.vim:

function! s:inCodeFence()
    " Search backwards for the opening of the code fence.
	call search('^```.*$', 'bceW')
    " Move one line down
	normal! j
    " Move to the begining of the line at start selecting
	normal! 0v
    " Search forward for the closing of the code fence.
	call search("```", 'ceW')

	normal! kg_
endfunction

function! s:aroundCodeFence()
    " Search backwards for the opening of the code fence.
	call search('^```.*$', 'bcW')
	normal! v$
    " Search forward for the closing of the code fence.
	call search('```', 'eW')
endfunction

xnoremap <buffer> <silent> if :call <sid>inCodeFence()<cr>
onoremap <buffer> <silent> if :call <sid>inCodeFence()<cr>
xnoremap <buffer> <silent> af :call <sid>aroundCodeFence()<cr>
onoremap <buffer> <silent> af :call <sid>aroundCodeFence()<cr>

I recently had to setup an Apple Push Notification service (APNs) server inside a Kubernetes cluster. The official documentation is somewhat hard to find and I found the process not to be that straightforward, especially when you spice it up a bit with some Kubernetes.

Given the ubiquitous need of apps to send notifications, I can only presume that most people rely of SaaS services such as Firebase.

Things we’ll talk about

APNs

APNs is apple’s service to allow mobile application developers to push notifications to their users. I also discovered that notifications can be distributed silently (ie. without the user seeing a UI element); this can be useful when you want to send a message to your app from your server backend, to implement a kind of push for instance.

Upon first launch, your application will request a unique ID from APNs, this ID is bound to this app instance and this device.

You would usually store this on your server so that you can reach this client at a later point.

gorush

Since I wasn’t too keen on implementing this all by myself, and wasn’t too keen on paying a SaaS for this need either, I set out to find what’s readily available.

Enter gorush, is a neat little bit of software written in go which implements both Apple (APNs) and Google’s (FCM). Perfect fit!

The setup is fairly simple, all of the configuration is done by editing the provided YAML file.

Walkthrough

Getting a token from Apple

There are two ways to authenticate your provider with APNs, a token-based approach, and a certificate-based one.

The token base method seems much more practical to set up (and maintain, since it does not require renewal, can be used for any number of your apps), and my guess is that the certificate based one is mostly around for legacy support.

To get a token, go to your apple developer console and create a new key.

Once create you will be given the opportunity to download your token (iirc this can only be done at this point, you won’t be able to download it later).

The file should be something like Authkey_KEYID.p8, with KEYID being this key’s ID (you will need that ID later on).

Store this somewhere safe, like in your password manager of choice.

Testing your token

gorush also ships with a command line utility which is very handy for debugging or just testing things out.

On macOS you can install it via Homebrew using:

brew install --HEAD https://github.com/appleboy/gorush/raw/master/HomebrewFormula/gorush.rb

To test that your token works, try the following:

gorush -ios -m 'hi' -team-id YOUR_IOS_TEAMID -key-id YOUR_KEYID -i AuthKey_XXXX.p8 -t AN_APNS_TOKEN --topic com.myapp.app

Replace YOUR_IOS_TEAMID with your team ID (which can be found on your developer console at the top right).

Replace YOUR_KEYID with the key id mentioned above.

Replace AN_APNS_TOKEN with a token you got from an actual device, I don’t think simulators can generate token, but I’m not sure.

Replace com.myapp.app by your app’s bundle identifier.

Note: when running a development build you will be granted a development token, this is not important for token based authentication, but certificate-based authentication make a distinction between production and development tokens, each having their own certificate.

If you didn’t fuck anything up, you should now see a nice and pretty generic notification pop up on your device ! Congratulations 🎉.

Setting it up in Kubernetes

Deploying gorush

Gorush ships with some manifest files that make it easy to deploy on k8s, all the k8s related files are located under the directory of the same name in the gorush repo, over here.

First we’ll adjust some settings, edit the gorush-configmap.yaml to your liking and apply it (as above for the namespace).

Note: gorush uses the Viper go module which allows to define runtime variables, the configmap vaules will be used in the gorush-deployment file and set as environment variables (the viper var stat.engine can be used as an env with GORUSH_STAT_ENGINE); you can name your configmap entries anything you want, but make sure you export the correct env var name. A list of all settings can be found in gorush’s code by greping “viper”.

Here are my edits to the configmap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: gorush-config
  namespace: gorush
data:
  # stat
  stat.engine: redis
  stat.redis.host: redis:6379
  ids.team: XXXXXX
  ids.key: XXXXXX
  ios.enabled: yep
  ios.key_path: /etc/secrets/authkey.p8
  ios.key_type: p8

And the corresponding edits in the gorush-deployment.yaml file:

- name: GORUSH_IOS_TEAM_ID
  valueFrom:
    configMapKeyRef:
      name: gorush-config
      key: ids.team
- name: GORUSH_IOS_KEY_ID
  valueFrom:
    configMapKeyRef:
      name: gorush-config
      key: ids.key
- name: GORUSH_IOS_ENABLED
  valueFrom:
    configMapKeyRef:
      name: gorush-config
      key: ios.enabled
- name: GORUSH_IOS_KEY_PATH
  valueFrom:
    configMapKeyRef:
      name: gorush-config
      key: ios.key_path
- name: GORUSH_IOS_KEY_TYPE
  valueFrom:
    configMapKeyRef:
      name: gorush-config
      key: ios.key_type

Storing your authKey in Kubernetes

Create a authkey-secret.yaml file with the following contents:

---
apiVersion: v1
kind: Secret
metadata:
name: ios-apns-auth-key
namespace: gorush
type: Opaque
stringData:
    ios-push-rsa-key: |
        -----BEGIN PRIVATE KEY-----
        MIGTAgXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
        ....
        -----END PRIVATE KEY-----

Replace the bit with BEGIN PRIVATE KEY with the contents of your AuthKey.p8 file and apply this manifest.

Edit the gorush-deployment.yaml file once again to mount this secret:

-- ...
spec:
  volumes:
  - name: ios-apns-auth-key
    secret: # <- this
      secretName: ios-apns-auth-key
  containers:
  - image: appleboy/gorush
    name: gorush
    imagePullPolicy: Always
    volumeMounts: # <- that
      - name: ios-apns-auth-key
        mountPath: /etc/secrets/
        readOnly: true
-- ...

Gorush service

If you only plan to use gorush within your cluster, eg. not exposed on the web (which I suggest), make sure to edit the gorush-service.yaml file and set the type to ClusterIP, this will make the service routeable only within the cluster.

Apply everything!

$> kubectl apply -f k8s/gorush-namespace.yaml
$> kubectl apply -f k8s/gorush-configmap.yaml
$> kubectl apply -f k8s/gorush-redis-deployment.yaml
$> kubectl apply -f k8s/gorush-redis-service.yaml
$> kubectl apply -f k8s/gorush-deployment.yaml
$> kubectl apply -f k8s/gorush-service.yaml

Testing the setup

Spawn a temporary container to check that the server is setup correctly.

$> kubectl run tmp-shell --rm -i --tty -image alpine -- sh

Inside the container install curl and test the endpoint!

$> apk add curl
$> curl gorush.gorush.svc.cluster.local
{"text":"Welcome to notification server."}

If you see a similar output, congrats once again, you’ve done it 🎉.

If you need to debug your config, you can dump it by curling gorush.gorush.svc.cluster.local/api/config, also pretty handy.

Sending out a test notification

Run your temporary container once more, create a JSON file with the following content:

{
  "notifications": [
    {
      "tokens": ["AN_APNS_TOKEN"],
      "platform": 1, # 1 is for iOS
      // "production": true, #Only for production tokens
      "title": "Le title",
      "topic": "YOUR_APP_BUNDLE",
      "alert": {
        "body": "le body"
      }
    }
  ]
}

Then run:

$> curl -X POST --data @notification.json http://gorush.gorush.svc.cluster.local/api/push

Again, congrats if you see a notification on your device ! 🎉

Happy notifying.

Links

• APNs overview
• Setting up a Token-based APNs connection
• gorush, A push notification micro server

One of the main reasons I switched to Neovim was the advertised Remote Plugin architecture. From that link:

Extensibility is a primary goal of Nvim. Any programming language may be used to extend Nvim without changes to Nvim itself. This is achieved with remote plugins, coprocesses that have a direct communication channel (via |RPC|) with the Nvim process.

I’ve never really liked Vim Script, tho admittedly I never spent too much time to learn it. And there are a million reason why, which I won’t get into here.

Well one language I use daily is Typescript, but setting it all up can be confusing. So I created a little boilerplate repository with everything setup so all you have to do is get to coding !

The code and instructions are over here.

Have fun!

Back in the days people used to have comment sections on their websites, and for a time it was good.

But for more than a decade now , you can’t just have a comment section without seeing it spammed to shits by various bots advertising unspoken goods.

In the previous iteration of this blog I have been using Disqus, but as many have stated, this is yet another “Free Product ™” trying to narrow down who you are so that a company down the line can sell your profile to someone; but I digress.

Some time ago I stumbled upon a blog post with a very sexy idea that I never got around to implementing: Use Github issues as means for comments! Brilliant!

Well now it’s done.

<script type="text/javascript">
    function domReady(fn) {
        document.addEventListener('DOMContentLoaded', fn);
        if (document.readyState === 'interactive' || document.readyState === 'complete') {
            fn();
        }
    }

    async function getComments(url = '') {
        const response = await fetch(url, {
            method: 'GET',
            mode: 'cors',
            cache: 'no-cache',
            headers: { Accept: 'application/vnd.github.v3.html+json' },
        });
        return response.json();
    }

    domReady(() => {
        const apiUrl =
            'https://api.github.com/repos/pyrho/25.wf-comments/issues/$githubIssueId$/comments';
        const appendComments = function (comments) {
            const commentSection = document.querySelector('comments');
            if (!comments || !comments.forEach || comments.length === 0) {
                commentSection.insertAdjacentHTML('beforeend', '<p>No comments yet.</p>');
                return;
            }
            comments.forEach(function (comment) {
                commentSection.insertAdjacentHTML(
                    'beforeend',
                    '<div class="comment"> ✿\
            <a class="commenter" href="' +
                        comment.user.html_url +
                        '"\
              target="_blank">' +
                        comment.user.login +
                        '</a> on ' +
                        new Date(comment.created_at).toUTCString() +
                        comment.body_html +
                        '</div>',
                );
            });
        };
        getComments(apiUrl).then(appendComments);
    });
</script>

I modified the script from the original author so that it’s vanilla JS (no ugly jQuery, come on it’s 2020). You can check the whole code at sr.ht where the code for this blog is hosted.

As stated by the original author, the main drawbacks of this method is that it limits the ability to comment to people with a Github account, while I hate this idea (of forcing people into a “walled garden”), let’s face it, anyone likely to read my ramblings (if anyone is actually reading this..) has a Github account.

Comment away !

For no valid reason I migrated my blog from Jekyll to Hakyll. Jekyll has served me well over the years, but I’m not much of a ruby guy; and Jekyll is probably the only reason I have Ruby installed on my system.

I’m trying to pick up Haskell in my spare time and I tought this would be a Fun ™ way of getting face to face with Haskell.

I also got obsessed with JuneGunn’s excellent Seoul256 vim colorscheme so I updated the blog’s looks too P:

You can find the code for this blog over here.

I snatched an old macbook air from a friend who was letting it gather dust.

My initial ambition was to use it like I would use an iPad, mostly to read stuff online when I’m too lazy to undock my main laptop.

Nothing to blog about I hear you say ! Well it was a pretty rough battle with the nvidia drivers, so I thought I’d share.

Hardware

• New battery from amazon
• New m.2 drive from amazon
• m.2 adapter to fit in the motherboard, I actually fucked up and bought the wrong one :D it’s either this OR that I’m too lazy to open up the mac and figure out :/ Sorry

Note that these are not affiliate links, I hate amazon and feel bad for linking it here but sometimes you just can’t do without them…

Software

I went with the latest Ubuntu 20.04, it usually has all the little quirks shipped with it so that almost anything runs without a hitch…. Most of the time that is.

There were three issues: - Cannot adjust brightness - Cannot sleep - Crappy framerate

Which all ended being caused by the same root cause.

Sleep issue and fucking nvidia drivers

During the ubuntu install if you choose to include non-free software (sorry rms), it will install the latest official nvidia drivers, as opposed to the open source “nouveau” drivers.

The graphics seemed a bit clunky at first, like low frame rate but I just chugged it to the macbook being old hardware.

Closing the lid would not make the mac sleep, other than that everything else was pretty smooth.

Trying to fix the lid issue was a real PITA, there are lot of people suggesting a lot of different things out there, Ubuntu has one of the biggest linux community so the Signal to Noise ratio is pretty low…

Then I found this stackoverflow answer which changed everything ! The instructions are not straight forward but if you do exactly as he says, you will fix your issue, no point in me paraphrasing here, click that link and do what the guy says.

Random interwebz suggestions

I did not modify my GRUB config.

I did not blacklist the nouveau modules.

I did uninstall GDM3 to replace it with LightDM, apparently some people are reporting that that fixed their issue; I can only report that this alone did not fix it for me.

And now my Macbook air runs smooth af (:)

TL;DR

If you are using a Persistent Volume Claim (PVC) and have the following issue:

Multi-Attach error for volume "pvc-X" Volume is already used by pod(s) Y

Changing your deployment from:

apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 1
  template:
  ...

to

apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 1
  strategy:
    type: Recreate # <-- That's the important part
  template:        # Not sure YAML accepts EOL comments...
  ...              # meh.

will fix your issue. Read on for more deets.

Background

I’ve been learning kubernetes on the job lately, it’s a rough ride… I’m hoping to write my experience with this beast sometime in the future.

I’ve had for the past months and did not find an proper workaround for it besides just trying over and over until it fixes itself… And today I finally found a proper fix for it so I’m sharing this here so that:

1. I can remember wtf I did
2. Other people encountering this issue could maybe stumble on this obscure part of the internet which is this page

The setup

I have a deployment which has a Persistent Volume Claim (PVC from now on) so that my service can store some persisting data.

PVC have different access modes, to cite the documentation:

• ReadWriteOnce – the volume can be mounted as read-write by a single node
• ReadOnlyMany – the volume can be mounted read-only by many nodes
• ReadWriteMany – the volume can be mounted as read-write by many nodes

DigitalOcean (where my shit is hosted) only offers ReadWriteOnce PVCs.

Where it gets interesting

As is fairly common, I have a Service with it’s corresponding Deployment, this Deployment has a PVC to store some persistent data (which would otherwise be lost each time the pod is deleted, and pods should always be considered disposable).

And if your setup is similar, you’ve probably already seen the dreaded: Multi-Attach error for volume "pvc-X" Volume is already used by pod(s) Y. Preventing the new version of your deployment to be deployed.

The issue is that by default, Kubernetes will use what’s called a RollingUpdate. And in most cases it’s exactly what you want, Kube will only kill v1 of your deployment once the new v2 version is Ready to accept incoming traffic (maybe the deployment needs to bootstrap some data, load a bunch of files, connect to a DB, etc.).

This allows your app to have virtually no downtimes as you rollout newer versions of your code.

This does not work in my case however, because for the v2 pod to be ready it needs to have the PVC attached to its pod; but since that PVC is already attached to the v1 pod this can never happen, resulting in an infinite deadlock.

Enter Recreate

A more brutal but necessary-in-this-setup method is to use the Recreate DeploymentStrategy. This will immediately kill the old version of your deployment, freeing the PVC so that the newer version can spawn a pod.

Closing thoughts

Writing this it really feels like it should not have taken me this long to figure a solution to this issue. Googling around did not yield an immediate answer, and I stumbled upon the workaround by reading a random suggestion from a random dude on a random github issue.

Maybe if I had just RTFM…..