In my earlier post I used a hacked together shield for building a clock based on Adafruit’s NeoPixel/WS2812 (“LED Clock with Kitchen Hot Pan Protector“). The new design supports now 8 parallel data streams, integrated realtime clock and wireless connectivity with the nRF24L01+ module.

NeoPixel Shield

The shield uses a high-speed HT245/74HCT245 levels shifter to transform the 3.3V signals from the FRDM board to the 5V required by the WS2812 LEDs. The shield features a DS1342 realtime clock which is now supported by the RTC_Maxim Realtime Clock component too. The coin cell is recharged if the board is powered.

The nRF24L01+ module has been added to the shield so I can control it remotely.

The board features a 5V DC supply (directly from the FRDM 5V header) to allow to run a small amount of LEDs (keep in mind that each LED takes up to 30 mA!). Using less than 10 LEDs no external power supply is needed.

The board has 8 data lines using the pins PTC0 to PTC7 of the KL25Z microcontroller. With this, each RBG LED only requires three bytes of RAM, so with a single FRDM-KL25Z board which has 16 KByte of RAM I can control more than 5000 LEDs!

WS2812 Timing with DMA

In my earlier project (“First Adafruit NeoPixel Blinks with the FRDM Board“) I already used DMA with PWM to control the pixels, but only on one channel. And for each data bit I needed 16bits of RAM. This works up to a small amount of LED’s (<200), but then I will run out of RAM easily. A different approach was needed to save RAM. The idea is to use an 8bit data port and use it to ‘bang’ the pixels out. The approach is nothing new (e.g. the Teensy is doing the same thing).

I’m using the TPM0 timer module on the KL25Z:

1. Start the timer
2. When channel 0 matches (CH0 Event), it triggers a DMA event which writes 0xff to the port to pull up all data lines.
3. When channel 1 matches (CH1 Event), it triggers a DMA event which writes the data (8bit) to the port. With this the data bits (RGB values) are shifted to the lanes.
4. When the timer overflows, it writes 0x00 to the port to pull down all data lines.

To meet the fast and narrow timing requirements, I’m using TPM0 with a 48 MHz base clock. The timer will overflow after 54 ticks (1.146 us) with a channel 0 module counter of 18 (0.396 us) and channel 1 modulo counter of 36 (0771 us):

I’m using the Init_TPM component only to initialize the base of the timer. Everything else I’m doing in the code directly with PDD macros. The timer gets initialized with PDD too:

static void InitTimer(void) {
  TPM_PDD_WriteStatusControlReg(TPM0_DEVICE, 0); /* init timer status and control register */
  TPM_PDD_InitializeCounter(TPM0_DEVICE); /* reset timer counter */
  TPM_PDD_WriteModuloReg(TPM0_DEVICE, (3*18)); /* set overflow to 1.25 us */
  TPM_PDD_WriteChannelValueReg(TPM0_DEVICE, 0, 18); /* channel 0 match at 0.4 us */
  TPM_PDD_WriteChannelValueReg(TPM0_DEVICE, 1, 36); /* channel 1 match at 0.8 us */
}

Similar to the timer, the DMA channels get initialized using PDD macros:

static void InitDMA(void) {
  InitTimer(); /* timer setup */
  /* setup address modulo: we are not using it as we stream out the data once and then latch it */
  DMA_PDD_SetSourceAddressModulo(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, DMA_PDD_CIRCULAR_BUFFER_DISABLED); /* circular buffer */
  DMA_PDD_SetSourceAddressModulo(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, DMA_PDD_CIRCULAR_BUFFER_DISABLED); /* circular buffer */
  DMA_PDD_SetSourceAddressModulo(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, DMA_PDD_CIRCULAR_BUFFER_DISABLED); /* circular buffer */
  /* the 'set all bits' and 'clear all bits' DMA events will use a single value, so no address increment.
   * But for the data we will increment the source address counter
   */
  DMA_PDD_EnableSourceAddressIncrement(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, PDD_DISABLE); /* source address incremented by transfer size */
  DMA_PDD_EnableSourceAddressIncrement(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, PDD_ENABLE); /* source address incremented by transfer size */
  DMA_PDD_EnableSourceAddressIncrement(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, PDD_DISABLE); /* source address incremented by transfer size */
  /* we transfer one byte every time */
  DMA_PDD_SetSourceDataTransferSize(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, DMA_PDD_8_BIT); /* Transfer size from source is 8bit */
  DMA_PDD_SetSourceDataTransferSize(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, DMA_PDD_8_BIT); /* Transfer size from source is 8bit */
  DMA_PDD_SetSourceDataTransferSize(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, DMA_PDD_8_BIT); /* Transfer size from source is 8bit */
  /* set up destination address:
   * PSOR (Port Set Output Register) will use 0xff to set the bits
   * PDOR (Port Data Output Register) will use the data
   * PDCR (Port Data Clear Register) will use 0xff to clear the bits
   */
  DMA_PDD_SetDestinationAddress(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, (uint32_t)&GPIOC_PSOR); /* set destination address: address of PTC Output register */
  DMA_PDD_SetDestinationAddress(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, (uint32_t)&GPIOC_PDOR); /* set destination address: address of PTC Output register */
  DMA_PDD_SetDestinationAddress(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, (uint32_t)&GPIOC_PCOR); /* set destination address: address of PTC Output register */
  /* no destination address buffer module: we will stream data only once */
  DMA_PDD_SetDestinationAddressModulo(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, DMA_PDD_CIRCULAR_BUFFER_DISABLED); /* no circular buffer */
  DMA_PDD_SetDestinationAddressModulo(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, DMA_PDD_CIRCULAR_BUFFER_DISABLED); /* no circular buffer */
  DMA_PDD_SetDestinationAddressModulo(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, DMA_PDD_CIRCULAR_BUFFER_DISABLED); /* no circular buffer */
  /* no destination address increments needed */
  DMA_PDD_EnableDestinationAddressIncrement(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, PDD_DISABLE); /* no auto-increment for destination address */
  DMA_PDD_EnableDestinationAddressIncrement(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, PDD_DISABLE); /* no auto-increment for destination address */
  DMA_PDD_EnableDestinationAddressIncrement(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, PDD_DISABLE); /* no auto-increment for destination address */
  /* we are transferring 1 byte of data */
  DMA_PDD_SetDestinationDataTransferSize(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, DMA_PDD_8_BIT); /* Transfer to destination size is 16bit */
  DMA_PDD_SetDestinationDataTransferSize(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, DMA_PDD_8_BIT); /* Transfer to destination size is 16bit */
  DMA_PDD_SetDestinationDataTransferSize(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, DMA_PDD_8_BIT); /* Transfer to destination size is 16bit */
  /* at the and of the DMA sequence, disable DMA */
  DMA_PDD_EnableRequestAutoDisable(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, PDD_ENABLE); /* disable DMA request at the end of the sequence */
  DMA_PDD_EnableRequestAutoDisable(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, PDD_ENABLE); /* disable DMA request at the end of the sequence */
  DMA_PDD_EnableRequestAutoDisable(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, PDD_ENABLE); /* disable DMA request at the end of the sequence */
}

The more challenging part was then getting DMA to run properly on the KL25Z. While things worked well at a slower speed (say 3 us timer overflow time), it terribly failed when I reduced the timing down to 1.25 us: bit were not transmitted, DMA looses (????) events, DMA event triggered even if all flags are cleared and Timer DMA events disabled, with even the timer clock timer disabled. All kind of weird things :-(.

The screenshot below shows a case where it should first send 8 zero bits, but actually it sends an additional ‘ghost’ bit at the start of the DMA transfer:

In other cases it was loosing bits, and simply screwing up everything. Again, the problem only occurred when I was getting close to the 1.25 us timing period.

Reading the Freescale data sheets back and forward was no help, and I had not found and solutions in the usual forums. I was about to pull out my last hears, when I realized that when I disable the timer, it still runs internally for a while! For example if I reset the timer to zero and stop it, it still counts up to 0xE or even 0x15. So this definitely will cause an (internal) channel 0 event, even if events/DMA are disabled! Because of the device internal propagation delays, I cannot cleanly stop the timer before it hits the first DMA (internal) event, which then is latched and will cause a ‘ghost’ DMA event :-(.

It took me lot of trial-and-errors, but finally I have found a working solution:

1. Always clear the DMA done flags.
2. Write zero to the timer counter register, followed by clearing the timer event flags.
3. Have the Timer DMA bits only enabled during the actual transfer of the bits (although the auto-complete-and-disable feature of the DMA should take care of this, but if fails because of internal propagation delays of the KL25Z).
4. The only way to get rid of the internal DMA status bits and to get it forced back to a clean state, is to disable the DMA muxing and enable the muxing again: this seems to reset the internal state machine.

With this, everything finally is working as expected:

The code below shows the solution sequence with setting up the DMA transfer (which finally works) :-):

static uint8_t Transfer(uint32_t dataAddress, size_t nofBytes) {
  static const uint8_t OneValue = 0xFF; /* value to clear or set the port bits */
  TMOUT1_CounterHandle handle;
  bool isTimeout;
  uint32_t done0, done1, done2;

  /* clear any pending done flags for DMA channels */
  DMA_PDD_ClearDoneFlag(DMA_BASE_PTR, DMA_PDD_CHANNEL_0);
  DMA_PDD_ClearDoneFlag(DMA_BASE_PTR, DMA_PDD_CHANNEL_1);
  DMA_PDD_ClearDoneFlag(DMA_BASE_PTR, DMA_PDD_CHANNEL_2);
  /* set DMA source addresses */
  DMA_PDD_SetSourceAddress(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, (uint32_t)&OneValue); /* set source address */
  DMA_PDD_SetSourceAddress(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, dataAddress); /* set source address */
  DMA_PDD_SetSourceAddress(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, (uint32_t)&OneValue); /* set source address */
  /* set byte count addresses */
  DMA_PDD_SetByteCount(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, nofBytes); /* set number of bytes to transfer */
  DMA_PDD_SetByteCount(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, nofBytes); /* set number of bytes to transfer */
  DMA_PDD_SetByteCount(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, nofBytes); /* set number of bytes to transfer */
  /* reset TPM counter */
  TPM_PDD_InitializeCounter(TPM0_DEVICE); /* reset timer counter */
  TPM_PDD_ClearChannelFlags(TPM0_DEVICE, 0x00);
  TPM_PDD_ClearOverflowInterruptFlag(TPM0_DEVICE);
  /* re-enable DMA Muxing: it will disabled at the end of the transfer */
  DMAMUX_PDD_EnableChannel(DMAMUX0_BASE_PTR, 0, PDD_ENABLE);
  DMAMUX_PDD_EnableChannel(DMAMUX0_BASE_PTR, 1, PDD_ENABLE);
  DMAMUX_PDD_EnableChannel(DMAMUX0_BASE_PTR, 2, PDD_ENABLE);
  /* enable DMA peripheral requests */
  DMA_PDD_EnablePeripheralRequest(DMA_BASE_PTR, DMA_PDD_CHANNEL_2, PDD_ENABLE); /* enable request from peripheral */
  DMA_PDD_EnablePeripheralRequest(DMA_BASE_PTR, DMA_PDD_CHANNEL_1, PDD_ENABLE); /* enable request from peripheral */
  DMA_PDD_EnablePeripheralRequest(DMA_BASE_PTR, DMA_PDD_CHANNEL_0, PDD_ENABLE); /* enable request from peripheral */
  /* clear timer flags and status so it starts from a clean starting point */
  TPM_PDD_ClearChannelFlags(TPM0_DEVICE, 0x00);
  TPM_PDD_ClearOverflowInterruptFlag(TPM0_DEVICE);
  /* enable TPM DMA */
  TPM_PDD_WriteStatusControlReg(TPM0_DEVICE,TPM_PDD_ReadStatusControlReg(TPM0_DEVICE)|TPM_SC_DMA_MASK);
  TPM_PDD_EnableChannelDma(TPM0_DEVICE, 1);
  TPM_PDD_EnableChannelDma(TPM0_DEVICE, 0);
  /* start the TPM timer */
  StartTimer();
  //Bit2_SetVal(); /* toggle pin for debugging purpose */

  isTimeout = FALSE;
  handle = TMOUT1_GetCounter(100/TMOUT1_TICK_PERIOD_MS);
  for(;;) {
    /* wait until transfer is complete */
    if (TMOUT1_CounterExpired(handle)) {
      isTimeout = TRUE;
      break; /* leave loop */
    }
    done0 = DMA_PDD_GetDoneFlag(DMA_BASE_PTR, DMA_PDD_CHANNEL_0);
    done1 = DMA_PDD_GetDoneFlag(DMA_BASE_PTR, DMA_PDD_CHANNEL_1);
    done2 = DMA_PDD_GetDoneFlag(DMA_BASE_PTR, DMA_PDD_CHANNEL_2);
    if (done0 && done1 && done2) {
      break; /* done! */
    }
    WAIT1_WaitOSms(1); /* give back some time */
  }
  TMOUT1_LeaveCounter(handle);
  WAIT1_Waitus(50); /* latch, low for at least 50 us (40x1.25us) */

  /* disable DMA-Muxing: necessary, otherwise DMA events on TPM0 channel 0 might be still latched.
   * Will enable muxing for next transfer */
  DMAMUX_PDD_EnableChannel(DMAMUX0_BASE_PTR, 0, PDD_DISABLE);
  DMAMUX_PDD_EnableChannel(DMAMUX0_BASE_PTR, 1, PDD_DISABLE);
  DMAMUX_PDD_EnableChannel(DMAMUX0_BASE_PTR, 2, PDD_DISABLE);
  /* disable peripheral DMA */
  TPM_PDD_WriteStatusControlReg(TPM0_DEVICE,TPM_PDD_ReadStatusControlReg(TPM0_DEVICE)&(~TPM_SC_DMA_MASK));
  TPM_PDD_DisableChannelDma(TPM0_DEVICE, 1);
  TPM_PDD_DisableChannelDma(TPM0_DEVICE, 0);

  StopTimer(); /* stop TPM */

  //Bit2_ClrVal(); /* toggle pin for debugging purpose */

  if (isTimeout) {
    return ERR_BUSY;
  }
  return ERR_OK;
}

Demo Project

All the software and drivers are in an Eclipse project, available on GitHub (link at the end of the article). It uses FreeRTOS and the RNet wireless stack:

Summary

A data sheet or reference manual does not tell you every (important!) detail of the chip. Probably because the designers of the chip do not write that documentation, but someone else who does not have that insight. Peripherals like timers have sometimes some weird behaviour, as they have internal delays, latches and all kind of things which can cause troubles. Viewing at the bits with the debugger does not tell every internal meta-state of the hardware. In my case the timer was still running on for a while in the hardware, even if I have stopped it from the firmware. That skew of the timer caused internal DMA triggers (even if DMA disabled?) and therefore screwed up everything. In my case, turning off muxing and turning it on again enforced a clean reset of the DMA engine, and finally the bits were DMA’ed out as expected.

The sources of this project are available on GitHub here. The schematics (Altuim) can be found on GithHub here.

Happy Pixeling 🙂

Links:

• First Adafruit NeoPixel Blinks with the FRDM Board
• Adafruit NeoPixel Clock with 60 LEDs
• LED Clock with Kitchen Hot Pan Protector
• Tutorial: Ultra Low Cost 2.4 GHz Wireless Transceiver with the FRDM Board