wirtz
/
uClock
mirror of https://github.com/midilab/uClock
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #35 from doctea/software-version

Browse Source 
Fallback to a hardware-agnostic "Software mode" on unsupported boards, or as a compile-time option
main
midilab 1 week ago committed by GitHub
parent c0196f31a2 3f5b20a924
commit 594d5ab0fd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 133 additions and 46 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 22
      README.md
  2. 2
      library.json
  3. 2
      library.properties
  4. 37
      src/platforms/software.h
  5. 109
      src/uClock.cpp
  6. 5
      src/uClock.h

22
README.md
Unescape View File

@ -17,6 +17,26 @@ The uClock library API operates through attached callback functions mechanism:
4. **setOnClockStart(onClockStartCallback) > onClockStartCallback()** on uClock Start event
5. **setOnClockStop(onClockStopCallback) > onClockStopCallback()** on uClock Stop event
### Software Timer mode - for unsupported boards (or avoiding usage of interrupts)
If a supported board isn't detected during compilation then a generic fallback approach will be used. This does not utilise any interrupts and so does not ensure accurate timekeeping. This can be useful to port your projects to boards that do not have support in uClock yet, or to test if suspected bugs in your code are related to interactions with interrupts or task handling.
You can force this non-interrupt "software timer mode" even on supported boards by defining the build flag `USE_UCLOCK_SOFTWARE_TIMER`.
In order for software timer mode to work, you need to add a call to your `loop()` function to process ticks. For example,
```c++
void loop() {
uClock.run();
// do anything else you need to do inside loop()...
// you can intercalate your main processing with other uClock.run() calls to avoid timming accuracy loss.
//uClock.run();
// do anything other inside loop()...
//uClock.run();
// the faster you can call uClock.run() without blocking the better and accurate timming you can achieve.
}
```
## Set your own resolution for your clock needs
1. **PPQN_24** 24 Pulses Per Quarter Note
@ -34,7 +54,7 @@ Furthermore, it is possible to utilize all three resolutions simultaneously, all
## uClock v2.0 Breaking Changes
If you are coming from uClock version < 2.0 versions pay attention to the breaking changes so you can update your code to reflect the new API interface:
If you are coming from uClock version < 2.0 versions, pay attention to the breaking changes so you can update your code to reflect the new API interface:
### setCallback function name changes

2
library.json
Unescape View File

@ -1,6 +1,6 @@
{
"name": "uClock",
"version": "2.1.0",
"version": "2.2.0",
"description": "A Library to implement BPM clock tick calls using hardware interruption. Supported and tested on AVR boards(ATmega168/328, ATmega16u4/32u4 and ATmega2560) and ARM boards(Teensy, STM32XX, ESP32, Raspberry Pico, Seedstudio XIAO M0 and RP2040)",
"keywords": "bpm, clock, timing, tick, music, generator",
"repository":

2
library.properties
Unescape View File

@ -1,5 +1,5 @@
name=uClock
version=2.1.0
version=2.2.0
author=Romulo Silva <contact@midilab.co>
maintainer=Romulo Silva <contact@midilab.co>
sentence=BPM clock generator for Arduino platform.

37
src/platforms/software.h
Unescape View File

@ -0,0 +1,37 @@
#include <Arduino.h>
/*
Generic fallback approach that doesn't rely on any particular MCU's interrupts or RTOS threads etc.
Simply checks micros() and compares last time tick happened and interval size to determine when a tick is due.
requires calling softwareTimerHandler(micros()); inside loop() in order to trigger tick processing.
function signature: void softwareTimerHandler(uint32_t micros_time);
@author Doctea
*/
#define ATOMIC(X) X;
// forward declaration of ISR
void uClockHandler();
uint32_t uclock_last_time_ticked;
uint32_t uclock_us_interval;
// call this as often as possible to tick the uClock
void softwareTimerHandler(uint32_t micros_time) {
if (micros_time - uclock_last_time_ticked >= uclock_us_interval) {
uclock_last_time_ticked = micros_time;
uClockHandler();
}
}
void initTimer(uint32_t init_clock)
{
// basically nothing to do for software-implemented version..?
uclock_last_time_ticked = micros();
}
void setTimer(uint32_t us_interval)
{
uclock_us_interval = us_interval;
}

109
src/uClock.cpp
Unescape View File

@ -2,7 +2,7 @@
* @file uClock.cpp
* Project BPM clock generator for Arduino
* @brief A Library to implement BPM clock tick calls using hardware interruption. Supported and tested on AVR boards(ATmega168/328, ATmega16u4/32u4 and ATmega2560) and ARM boards(RPI2040, Teensy, Seedstudio XIAO M0 and ESP32)
* @version 2.1.0
* @version 2.2.0
* @author Romulo Silva
* @date 10/06/2017
* @license MIT - (c) 2024 - Romulo Silva - contact@midilab.co
@ -27,43 +27,61 @@
*/
#include "uClock.h"
//
// General Arduino AVRs port
//
#if defined(ARDUINO_ARCH_AVR)
#include "platforms/avr.h"
#endif
//
// Teensyduino ARMs port
//
#if defined(TEENSYDUINO)
#include "platforms/teensy.h"
#endif
//
// Seedstudio XIAO M0 port
//
#if defined(SEEED_XIAO_M0)
#include "platforms/samd.h"
#endif
//
// ESP32 family
//
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP32)
#include "platforms/esp32.h"
#endif
//
// STM32XX family
//
#if defined(ARDUINO_ARCH_STM32)
#include "platforms/stm32.h"
// no hardware timer clock? use USE_UCLOCK_SOFTWARE_TIMER
#if !defined(USE_UCLOCK_SOFTWARE_TIMER)
//
// General Arduino AVRs port
//
#if defined(ARDUINO_ARCH_AVR)
#include "platforms/avr.h"
#define UCLOCK_PLATFORM_FOUND
#endif
//
// Teensyduino ARMs port
//
#if defined(TEENSYDUINO)
#include "platforms/teensy.h"
#define UCLOCK_PLATFORM_FOUND
#endif
//
// Seedstudio XIAO M0 port
//
#if defined(SEEED_XIAO_M0)
#include "platforms/samd.h"
#define UCLOCK_PLATFORM_FOUND
#endif
//
// ESP32 family
//
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP32)
#include "platforms/esp32.h"
#define UCLOCK_PLATFORM_FOUND
#endif
//
// STM32XX family
//
#if defined(ARDUINO_ARCH_STM32)
#include "platforms/stm32.h"
#define UCLOCK_PLATFORM_FOUND
#endif
//
// RP2040 (Raspberry Pico) family
//
#if defined(ARDUINO_ARCH_RP2040)
#include "platforms/rp2040.h"
#define UCLOCK_PLATFORM_FOUND
#endif
#endif
//
// RP2040 (Raspberry Pico) family
// Software Timer for generic, board-agnostic, not-accurate, no-interrupt, software-only port
//
#if defined(ARDUINO_ARCH_RP2040)
#include "platforms/rp2040.h"
#if !defined(UCLOCK_PLATFORM_FOUND)
#pragma message ("NOTE: uClock is using the 'software timer' approach instead of specific board interrupted support, because board is not supported or because of USE_UCLOCK_SOFTWARE_TIMER build flag. Remember to call uClock.run() inside your loop().")
#include "platforms/software.h"
#endif
//
// Platform specific timer setup/control
//
@ -125,7 +143,7 @@ void uClockClass::init()
uint32_t uClockClass::bpmToMicroSeconds(float bpm)
{
return (60000000 / ppqn / bpm);
return (60000000.0f / (float)ppqn / bpm);
}
void uClockClass::setPPQN(PPQNResolution resolution)
@ -193,13 +211,6 @@ void uClockClass::setTempo(float bpm)
setTimerTempo(bpm);
}
// this function is based on sync24PPQN
float inline uClockClass::freqToBpm(uint32_t freq)
{
float usecs = 1/((float)freq/1000000.0);
return (float)((float)(usecs/(float)24) * 60.0);
}
float uClockClass::getTempo()
{
if (mode == EXTERNAL_CLOCK) {
@ -218,6 +229,22 @@ float uClockClass::getTempo()
return tempo;
}
// for software timer implementation(fallback for no board support)
void uClockClass::run()
{
#if !defined(UCLOCK_PLATFORM_FOUND)
// call software timer implementation of software
softwareTimerHandler(micros());
#endif
}
// this function is based on sync24PPQN
float inline uClockClass::freqToBpm(uint32_t freq)
{
float usecs = 1/((float)freq/1000000.0);
return (float)((float)(usecs/(float)24) * 60.0);
}
void uClockClass::setMode(SyncMode tempo_mode)
{
mode = tempo_mode;

5
src/uClock.h
Unescape View File

@ -2,7 +2,7 @@
* @file uClock.h
* Project BPM clock generator for Arduino
* @brief A Library to implement BPM clock tick calls using hardware interruption. Supported and tested on AVR boards(ATmega168/328, ATmega16u4/32u4 and ATmega2560) and ARM boards(RPI2040, Teensy, Seedstudio XIAO M0 and ESP32)
* @version 2.1.0
* @version 2.2.0
* @author Romulo Silva
* @date 10/06/2017
* @license MIT - (c) 2024 - Romulo Silva - contact@midilab.co
@ -130,6 +130,9 @@ class uClockClass {
void setTempo(float bpm);
float getTempo();
// for software timer implementation(fallback for no board support)
void run();
// external timming control
void setMode(SyncMode tempo_mode);
SyncMode getMode();

Write Preview
Loading…
Cancel
Save