Repository navigation
developer_guide
When extending the Polyend Tracker Community Edition (CE) firmware, adding new synthesizer engines, or writing Sample Editor effects, keep the following hardware constraints and non-obvious architectural details in mind.
- Memory Budget & Free Headroom
- Shared
768 KBScratch Buffer Layout (externalRamScratchBuff) - Copy-on-Write
/Workspace/instruments/, Incremental Project Saver & Hybrid SD Streaming - Synthesizer Engine Architecture & Guidelines (
.psynPlugins) - Sample Editor &
.ptfxPlugin Constraints - UI, FT812 Display, Config & Bootloader Gotchas
- Conditional Compilation: Targeting Specific Platforms or Devices
- Development Console & Logging over USB (Tracker+ & Tracker Mini)
- Global File Browser (
GlobalFileBrowser)
| Platform & Memory Region | Total Capacity | Current Usage | Immediately Free | Theoretically Reclaimable | What Lives Here & Developer Notes |
|---|---|---|---|---|---|
Original (MK66) - FLASH |
1,024 KB |
~871 KB (85.1%) |
~153 KB |
— | Code, .rodata, .audio_ram_functions, compressed fonts & bitmaps. |
Original (MK66) - RAM (Internal SRAM) |
256 KB |
~128 KB (50.1%) |
~128 KB |
— | Stack, heap, .data, and real-time .bss. Cold UI/FileManager singletons live in EXTERNAL_RAM. |
Original (MK66) - EXTERNAL_RAM (SDRAM) |
16,384 KB |
~15,222 KB (92.9%) |
~1,162 KB (1.13 MB) |
+3.5–4.0 MB (up to ~5.1 MB total)
|
11.25 MB SAMPLE_MEMORY_SIZE (7.5 MB mono sample pool + 3.75 MB FX edit buffer) + 1.5 MB delay + 768 KB shared externalRamScratchBuff + VoiceStreamManager ring buffers + cold UI singletons. |
Plus / Mini (IMX) - QSPI_FLASH |
~16,200 KB |
~1,620–1,650 KB (10.0–10.2%) |
~14,570 KB |
— | XIP Flash; plenty of room for code, lookup tables, and assets. |
Plus / Mini (IMX) - SRAM_ITC (RAM2) |
128 KB |
~105.4 KB (82.4%) |
~22.5 KB |
— | Zero-wait-state instruction TCM (.ramfunc.$RAM2 / .audio_ram_functions hot DSP loops). |
Plus / Mini (IMX) - SRAM_DTC (RAM) |
352 KB |
~330–331 KB (93.9–94.0%) |
~21–22 KB |
— | Main stack, heap, .data, and real-time .bss. Keep large or non-realtime buffers in EXTERNAL_RAM. |
Plus / Mini (IMX) - SRAM_OC (RAM3) |
32 KB |
~22.7 KB (70.8%) |
~9.3 KB |
— | Non-cacheable OCRAM used for USB/SDMA buffers and audioRecBuff. |
Plus / Mini (IMX) - EXTERNAL_RAM (RAM4) |
65,536 KB |
~65,528 KB (99.99%) |
~8 KB |
+23.0 MB (up to ~23.0 MB total)
|
~54 MB SAMPLE_MEMORY_SIZE (~39 MB stereo sample pool + 15 MB FX edit buffer) + 6 MB PSYN_RAM_POOL_SIZE (1.92 MB .psyn arena + 4 MB synth SamplePool) + 1.5 MB delay + 768 KB externalRamScratchBuff + VoiceStreamManager ring buffers + 64 KB g_wtEnvelopeBank. |
By default, SAMPLE_MEMORY_SIZE in core/source/mtStructs.h maximizes sample RAM after accounting for PSYN_RAM_POOL_SIZE on IMX:
-
Original Tracker (
MK66):SAMPLE_MEMORY_SIZE = 45 * 256 * 1024(11.25 MB, comprising a7.5 MBresident mono sample pool plus3.75 MBEDIT_BUFF_SIZEreserved at the top for offline Sample Editor effects). -
Tracker+ & Tracker Mini (
IMX):PSYN_RAM_POOL_SIZE = 6 MB(6 * 1024 * 1024) is dedicated to loadable.psynsynth engines (1.92 MBexecutable arena) and the synthSamplePool(4 MB).SAMPLE_MEMORY_SIZE = ((60 * 1024 - 64) * 1024) - PSYN_RAM_POOL_SIZE(~54 MB, comprising a~39 MBresident stereo sample pool plus15 MB2 * SAMPLE_CHANNELS * EDIT_BUFF_SIZEreserved at the top for offline Sample Editor effects).
However, because Hybrid SD Card Sample Streaming (core/AudioEngine/VoiceStreamManager.cpp) streams samples >= 256 KB (kStreamThresholdBytes) directly from the SD card while only allocating a 32,768-frame (64 KB per channel) pre-cache in externalRamSampleMemory:
-
Future developers can chip away at
SAMPLE_MEMORY_SIZEwhenever a new feature requires additionalEXTERNAL_RAM, simply by loweringSAMPLE_MEMORY_SIZEincore/source/mtStructs.h:- On Tracker+ / Tracker Mini (
IMX), reducingSAMPLE_MEMORY_SIZEfrom~54 MBdown to31 MB(31 * 1024 * 1024, keeping the15 MBFX edit buffer + a16 MBresident sample pool for short samples, pre-caches, and Wavetable/Granular instruments) immediately frees~23 MBofEXTERNAL_RAM. - On Original Tracker (
MK66), reducingSAMPLE_MEMORY_SIZEfrom11.25 MB(45 * 256 * 1024) down to7.75 MB(31 * 256 * 1024, keeping the3.75 MBFX edit buffer + a4.0 MBresident sample pool) frees3.5 MBof additionalEXTERNAL_RAMon top of the1.13 MBalready unassigned (~4.63 MBtotal freeEXTERNAL_RAM).
- On Tracker+ / Tracker Mini (
-
Important when adjusting
SAMPLE_MEMORY_SIZE: Always keepSAMPLE_MEMORY_SIZE > 2 * SAMPLE_CHANNELS * EDIT_BUFF_SIZE(> 3.75 MBonMK66,> 15 MBonIMX) becauseEDIT_BUFF_OFFSET(externalRamEffectsBuff) is carved out of the top ofexternalRamSampleMemory.
Important (
SRAM_DTC/ InternalRAMvsEXTERNAL_RAM):
- Default
.bsslands inRAMon Original Tracker (MK66) andSRAM_DTCon Tracker+ / Tracker Mini (IMX), while__NOINIT(EXTERNAL_RAM)lands inEXTERNAL_RAM(.noinit_RAM4).- Because
.noinit_RAM4isNOLOAD(not zeroed by startup code before C++ static constructors run), any C++ singleton or state struct moved to__NOINIT(EXTERNAL_RAM)must be explicitly zeroed (memset) or Placement-newconstructed inTrackerImpl::init()before use.- Modal or mutually-exclusive features that only run when SD audio preview, offline stem export, and
.ptfxoffline execution are idle can shareexternalRamScratchBuff(768 KB) rather than declaring a new static buffer in.bssorEXTERNAL_RAM.
Defined in core/source/Tracker.cpp (SHARED_SCRATCH_MEMORY_SIZE = 768 * 1024 in core/source/mtStructs.h), the 768 KB externalRamScratchBuff array in EXTERNAL_RAM (.scratch_memory) is shared cleanly across subsystems (PtfxLoader / PtfxManager, mtAudioExport renderBuffer, mtAudioEngine sdStream, and GlobalFileBrowser).
When .ptfx Modular Sample Editor plugins and GlobalFileBrowser run concurrently, the 768 KB region is partitioned into four non-overlapping ranges:
Offset 0 KB 128 KB 512 KB 744 KB 768 KB
├─────────────────────────┼───────────────────────┼──────────────────────┼───────────────┤
│ .ptfx Code │ .ptfx Working Scratch │ .ptfx Secondary WAV │ Global File │
│ (128KB IMX / 32KB MK66) │ (384 KB) │ Buffer (232 KB) │ Browser (24KB)│
└─────────────────────────┴───────────────────────┴──────────────────────┴───────────────┘
-
kPtfxScratchTopOffset(512 KBincore/effector/ptfx_loader.h) caps.ptfxpluginscratch_memat384 KB([128 KB .. 512 KB]), leaving[512 KB .. 744 KB](232 KB) for pre-decoded secondary WAV files (PTFX_PARAM_FILE) and[744 KB .. 768 KB](24 KB) reserved forcGlobalFileBrowser. OpeningGlobalFileBrowserfrom inside the Sample Editor or an effect parameter never overwrites active plugin code, working scratch RAM, or loaded secondary audio, whileg_wtEnvelopeBank(64 KB) resides in its own dedicatedEXTERNAL_RAMarray incore/source/mtWavetableEnvelopes.cpp.
To avoid copying 13–45 MB of PCM sample payloads from /Projects/<Path>/<Name>/instruments/*.pti to /Workspace/instruments/instrument_%02d.pti on every project open and save, the FileManager uses a Header-Only Copy-on-Write (CoW) model paired with Hybrid SD Card Sample Streaming:
-
Project Open (
ProjectOpen::copyInstruments):- Copies only the 392-byte
strInstrumentFileheader (cFileTransfer::copyInstrumentHeader) from/Projects/<Path>/<Name>/instruments/*.ptiinto/Workspace/instruments/instrument_%02d.pti.
- Copies only the 392-byte
-
Sample Streaming & Reload (
WorkspaceProjectLoad&SampleMemoryReload):- In
cFileManager::startNewInstrumentSampleLoad()andcFileManager::loadSampleData(), if a/Workspace/instruments/instrument_%02d.ptifile hasfileSize <= sizeof(strInstrumentFile)(header-only), the loader resolves its backing.ptifile in/Projects/<Path>/<Name>/instruments/viacFileManager::resolveProjectInstrumentPtiPath()and loads or streams the PCM sample data directly from the project folder (respectingcFileManager::getPtiFileDataOffset()for both current 392-byte headers and legacy firmware< v8smaller headers).
- In
-
Copy-on-Write Promotion (
WorkspaceProjectSave& Sample Edits):- Parameter tweaks (
AutoSave/WorkspaceProjectSave) only rewrite the 392-byte header in/Workspace/instruments/instrument_%02d.ptiwhen!isInstrumentSampleChanged(idx), preserving its header-only status. - Whenever an instrument's audio is newly imported, recorded, rendered, copied (
InstrumentCopy), or modified in the Sample Editor (cFileManager::saveSampleDataToWorkspace), a full.ptifile (header + PCM audio) is written to/Workspace/instruments/instrument_%02d.pti.
- Parameter tweaks (
-
Incremental
Save Projectvs. FullSave As(ProjectSave::copyInstruments):-
Same-Project Save (
isSavingToSameProject == true): Deletes deactivated slots, copies full.ptifiles from/Workspace/only for slots whose audio was modified, and for unmodified header-only slots updates the 392-bytestrInstrumentFileheader in-place (skipping the write entirely if all 392 bytes are identical) and renames the file in-place ifsample.file_namechanged. -
Save Asto a New Project (isSavingToSameProject == false): Copies full.ptifiles from/Workspace/where present, and writes the updatedstrInstrumentFileheader plus the raw PCM sample payload directly fromexternalRamSampleMemory(or streams it in chunks from the backing.ptifile for SD-streamed instruments) for header-only slots so the new project folder is completely self-contained.
-
Same-Project Save (
-
Hybrid SD Card Sample Streaming Architecture (
VoiceStreamManager&isPlayModeStreamable):-
Threshold & SDRAM Pre-Cache: Instruments whose PCM payload is
>= 256 KB(kStreamThresholdBytesincore/source/mtStructs.h) and whose play mode satisfiesisPlayModeStreamable(playMode)allocate onlykStreamPreCacheFrames = 32768frames (~743 msat44.1 kHz) per channel (64 KBmono /128 KBstereo) inexternalRamSampleMemory. -
Zero-Latency Trigger & Background Ring Buffers: When a note is triggered, the audio ISR (
AudioPlayMemory::update()incore/libs/Audio/play_memory.cpp) immediately plays from the SDRAM pre-cache whileVoiceStreamManager::update()(core/AudioEngine/VoiceStreamManager.cpp) refills the active voice's16,384-frame (kRingFrames) ring buffer in4,096-frame (kChunkFrames) chunks on the main thread using FatFs FastSeek cluster link maps (CLMT) and direct LBA sector reads. -
Loop Wrap & Direction Support: Supports forward, backward, and ping-pong looping (
VoiceStreamManager::prepareLoopWrappre-fetches the loop boundary before the playhead reaches the wrap point) as well asR(Reverse) andP(Position) pattern step FX. -
Platform Differences (
PLATFORM_IMXvs.MK66):-
Tracker+ & Tracker Mini (
PLATFORM_IMX):isPlayModeStreamable()returnstrueforOne-Shot,Forward Loop,Backward Loop,Ping-Pong Loop,Slice, andBeat Slice, andfalseonly forWavetableandGranular. ForSliceandBeat Sliceinstruments, the32,768-frame SDRAM pre-cache is partitioned into a16,384-frame linear attack region ([0 .. 16383]) plus per-slice SDRAM pre-cache windows across the upper16,384frames (VoiceStreamManager::refreshInstrumentSliceCache/refreshInstrumentSingleSliceCache), allowing any slice to start immediately from SDRAM while the600 MHzCortex-M7 refills the voice ring buffer. -
Original Tracker (
MK66):isPlayModeStreamable()returnstrueforOne-Shot,Forward Loop,Backward Loop, andPing-Pong Loop, andfalseforSlice,Beat Slice,Wavetable, andGranular. Because partitioning16,384frames across10–48slices yields smaller per-slice pre-cache windows (~7.6–37 ms), and the180 MHzCortex-M4 spends~20–35 msper step on FT812 SPI pattern redraws and Song Mode pattern reads, keepingSliceandBeat Sliceinstruments 100% resident in SDRAM onMK66guarantees dropout-free multi-track slice playback while non-sliced instruments enjoy the full743 mslinear pre-cache.
-
Tracker+ & Tracker Mini (
-
Automatic Promotion & Demotion (
Sample Editor&Play ModeSwitching):- Entering the Sample Editor (
cSampleEditor) or switching an instrument to a non-streamable play mode (!isPlayModeStreamable(newPlayMode)infSamplePlay.cpp) callscFileManager::promoteStreamedInstrumentToRam(idx), loading the full PCM payload intoexternalRamSampleMemory. - Applying an offline Sample Editor effect or saving sample edits (
cFileManager::saveSampleDataToWorkspace) writes the updated full.ptito/Workspace/instruments/instrument_%02d.pti, recomputes the600-point waveform peak cache (WaveformPeakPoint), and callscFileManager::demoteRamInstrumentToStream(idx)to return the instrument to hybrid SD streaming.
- Entering the Sample Editor (
-
Threshold & SDRAM Pre-Cache: Instruments whose PCM payload is
-
Binary
.ptiHeader Compatibility (sizeof(strInstrument) == 372) & SharedenvWtPos/envGranLenAutomation Slot:- Because
strInstrumentFile(392bytes) is serialized directly into.ptifiles and Copy-on-Write/Workspace/instruments/headers,sizeof(strInstrument)incore/source/mtStructs.his enforced at372bytes viastatic_assert(sizeof(strInstrument) == 372). - Instrument structure versions
1–7may use the legacy368-byte metadata layout; versions8–9use372bytes. The 4-byte CRC field immediately follows the serialized metadata (though metadata-only legacy files may omit it). Loaders validate the header magic, version bounds, and metadata/file sizes before version translation, rejecting truncated, oversized, malformed, or newer-version metadata. -
Wavetable (
playModeWavetable) and Granular (playModeGranular) are mutually exclusive playback modes on an instrument. Therefore, Granular Length automation (envGranLen) shares envelope/LFO hardware storage slot3(envWtPos = 3,envGranLen = envWtPos) with Wavetable Position:- In the UI (
Instrument Automation 2/2), the 7 destinations are indexed byenAutomationDest(autoDestVolume,autoDestPanning,autoDestCutoff,autoDestWtPos,autoDestGranPos,autoDestGranLen,autoDestFinetune,autoDestCount = 7) and mapped to the 6 underlyingenvelope[6]/lfo[6]storage slots viaautomationDestToEnvSlot(uint8_t destIdx). - Enable state in
envelope[3].enableuses separate bitmask flags (kEnvEnableWtPosBit = 0x01forWavetable Position,kEnvEnableGranLenBit = 0x02forGranular Length) viastrInstrument::isWtPosEnvEnabled(),strInstrument::isGranLenEnvEnabled(),strInstrument::isEnvEnabled(envIdx),strInstrument::isAutomationDestEnabled(destIdx), andstrInstrument::setAutomationDestEnabled(destIdx, enabled). - Because all legacy
.ptifiles only ever wrote0or1(0x01) toenvelope[3].enable, existing.ptifiles load withisGranLenEnvEnabled() == false(Off) while preserving legacy Wavetable Position automation 100%. Always use theenvGranLenalias andisGranLenEnvEnabled()helper in granular code paths rather than rawenvWtPosor.enablechecks.
- In the UI (
- Because
Full details in docs/custom_synth_sdk.md and synth-plugin-sdk/README.md.
-
Loadable SD-Card
.psynArchitecture (PsynLoader):- All synth engines (built-in and community) are distributed as standalone ARMv7E-M Thumb-2 relocatable
.psynplugins in/Synths/*.psynon the microSD card and loaded dynamically byPsynLoader(PSYN_RAM_POOL_SIZE = 6 MBincore/source/mtStructs.h). -
PsynLoaderreserves1,920 KB(kArenaSize) for relocated.psyncode/heap (kMaxPreloadBytes = 1,024 KBpreloaded at boot, lazy load on demand, LRU eviction of inactive engines when full) alongside a shared4 MBSamplePoolfor sample-based engines (WAVS,GRAIN,DWA, and third-partyPSYN_FLAG_HAS_SAMPLE_SLOTSplugins). -
Zero firmware recompilation or bitmap edits required:
SynthEditorpopulates the Synth model list dynamically fromsynth->getSynthTypes(), and third-party engines receive deterministic non-colliding IDs (0x100+) when packed with--type-id-wave 0 --type-id-play-tracker 0.
- All synth engines (built-in and community) are distributed as standalone ARMv7E-M Thumb-2 relocatable
-
Auto-Created Sample Folders & Read Fallback Chain:
- On boot,
PsynLoadercreates/SynthSamples/<CODE_NAME>/for every sample-based engine (avoiding clutter in user/Samples/folders), whilecore/synth/FileSystemAdapter.cppresolves sample reads across/SynthSamples/,/Samples/,/, and/Patches/.
- On boot,
-
Keep Voice State & Arena Usage Compact (
CustomSynthVoice/ParamHelper):- Inherit from
polysynth::sdk::CustomSynthVoice<VoiceClass, ParamIdEnum>(synth/include/PolySynth/sdk/SynthVoiceSDK.h) bridged viaPSYN_REGISTER_CPP_VOICE(synth-plugin-sdk/include/psyn/psyn_cpp_bridge.h) or write a Pure Cpsyn_plugin_entryplugin (synth-plugin-sdk/include/psyn/psyn_plugin.h). - Never perform blocking
PsynHostApiSD/WAV calls (read_file,write_file,load_wav_file,free_wav_file) or heap allocations inside real-time audio callbacks (renderVoiceAudio/voice_render_audio).
- Inherit from
Full details in docs/modular_effects_system.md.
-
Plugin, Parameter, File & Preset Limits:
- Up to 128
.ptfxplugins (kMaxModularPlugins = 128incore/effector/ptfx_manager.h) are indexed from/Effects/alongside the 17 built-in Sample Editor effects (kBuiltInEffectsCount = 17,145total list items ins_effectDisplayNames). - Each
.ptfxplugin supports up to 12 parameters (PtfxHeader::params[12]incore/effector/tracker_plugin.handeditor-fx-sdk/tracker_plugin.h), including continuous float, stepped integer, pipe-separated string lists, and SD file pickers/savers (PTFX_PARAM_FILE/PTFX_PARAM_SAVE_FILE). - Any
.ptfxplugin with>= 1parameter automatically gains a Presets page via theMorescreen button (Load/Save.ptppresets in/Effects/Presets/<SanitizedPluginName>/viaGlobalFileBrowser, plusReset).
- Up to 128
-
.ptfxCode, Scratch & Secondary WAV Regions (externalRamScratchBuff):- Both platforms execute
.ptfxplugin code from the base ofexternalRamScratchBuff([0 .. 32 KB]on Original TrackerMK66with the Kinetis System MPU disabled viaMPU_CESR = 0, and[0 .. 128 KB]on Tracker+ / Tracker MiniIMXafter cleaning L1 D-Cache and invalidating I-Cache inPtfxLoader::syncInstructionCache()). - Working scratch memory (
scratch_mem, up to384 KB) occupies[128 KB .. 512 KB], leaving232 KBat[512 KB .. 744 KB]for pre-decoded secondary.wavinputs (get_secondary_sample(), up to ~118kint16_tsamples) and24 KBat[744 KB .. 768 KB]forGlobalFileBrowser. Plugins can also read/write non-WAV assets viahost->read_file()andhost->write_file(). - Plugins with
code_size + bss_size > 32 KB(or requiring 600 MHz Cortex-M7 speeds) should declarePTFX_FLAG_IMX_ONLY.
- Both platforms execute
-
SD Card DMA Alignment Pitfall on IMX (
FatFs+USDHC):- On IMX (
platforms/imx/),FatFs(f_read) bypasses its internal aligned DTCM sector buffer whenever a read request is>= 512bytes (cc = btr / 512 > 0) and passes the caller's destination pointer directly to the USDHC DMA controller. - If the destination buffer is not 4-byte aligned or lies in a non-DMA-accessible TCM region,
f_readfails withFR_DISK_ERR. Always use 4-byte aligned buffers inSRAM_DTC/EXTERNAL_RAM, or read in<= 256-byte chunks to forceFatFsthrough its internal bounce buffer (hostReadFileandhostWriteFileuse256-byte chunking automatically).
- On IMX (
-
Do Not Shift
Interface::modules[]Indices (core/interface/core/interface.cpp):- UI navigation references
mtInterface.modules[]by hardcoded index (modules[9]=performanceMode,modules[10]=imageViewer,modules[12]=masterParams). Slotmodules[11](formerly the NES emulatorgameModule) is intentionally kept asnullptrso higher indices never shift.
- UI navigation references
-
FT812 Font Buffer Cap (
22,396Bytes) & Embedded Hardware Icons:-
kMaxFontBufferSizeincore/libs/NewDisplay/display.cppis22,396bytes (decompressedFontsCommonBuffer). Every individual font slot (both built-in RLE-compressed fonts and.ptfontslots on SD) must decompress to<= 22,396bytes. -
Font Slot 4 (
17px Bold, FT812 Handle 4) embeds 8 custom hardware icons at ASCII0x18..0x1F(24..31:Pause,Stop,Play,Rec,Folder,Up-dir,Loop,Arrow). If these are missing from a font, transport bar and file browser icons will appear blank. -
Font Slot 5 (
12px Regular, FT812 Handle 5) embeds Polish diacritics at ASCII0x11..0x1F(17..31).
-
-
Bootloader
.ptfFilename Filter & 31-Character Limit:- The firmware updater (
enListFileFilter_firmwareinplatforms/mk66/3rdparty/SD/SD.cppandplatforms/imx/sdmmc/sd/SD.cpp) only lists files in/Firmware/that end with.ptf, have total length>= 15, and start with:-
PolyendTrac(Original Tracker) -
TrackerPlus(Tracker+) -
TrackerMini(Tracker Mini)
-
-
31-Character Maximum on Original Tracker:
PlatformImpl::runBootloader()(platforms/mk66/source/PlatformImpl.cpp/platforms/imx/source/PlatformImpl.cpp) writes the selected.ptffilename to/Firmware/_fwinfo. The Original Tracker's on-chip bootloader reads/Firmware/_fwinfointo a 32-bytechar[32]buffer. Filenames of 32+ characters overwrite the trailing\0byte and cause garbage symbols on the bootloader flashing screen. Always keep.ptffilenames<= 31characters.
- The firmware updater (
All three devices share the same core/ codebase and are differentiated at compile time by preprocessor defines set in core/makefile, platforms/mk66/makefile, and platforms/imx/makefile.
| Target Scope | Preprocessor Condition | Matching Hardware & Typical Use Case |
|---|---|---|
| IMX Only (Tracker+ & Mini) | #ifdef PLATFORM_IMX |
600 MHz Cortex-M7, 64 MB SDRAM, stereo samples (SAMPLE_CHANNELS == 2), 16 tracks. |
| MK66 Only (Original Tracker) | #ifndef PLATFORM_IMX |
180 MHz Cortex-M4F, 16 MB SDRAM, mono samples (SAMPLE_CHANNELS == 1), 16 tracks. |
| Tracker Mini Only | #ifdef TRACKER_MINI |
Handheld controls (interfaceButtonMiniMiddle, D-pad, battery gauge, internal mic, no pad grid). |
| Desktop Form Factor (Original & Plus) | #ifndef TRACKER_MINI |
Shared desktop hardware: 48 RGB silicone pads, rotary jog-wheel, FM radio, line/mic inputs. |
| Tracker+ Exclusively | #if defined(PLATFORM_IMX) && !defined(TRACKER_MINI) |
Features requiring both the IMX CPU/RAM and the 48-pad desktop interface. |
| Synth Audio Engine | #ifdef FEATURE_SYNTH |
Defined when PLATFORM=IMX; enables PolySynth and sets kSynthParts = 3 in core/config/config.h. |
| Synth UI Screens | #if GUI_HANDLE_SYNTH |
Defined as 1 (on PLATFORM_IMX) or 0 (on MK66) in core/interface/core/interfaceDefs.h. |
#if defined(PLATFORM_IMX)
// Runs on Tracker+ and Tracker Mini (600 MHz Cortex-M7)
#if defined(TRACKER_MINI)
// Tracker Mini only
#else
// Tracker+ only
#endif
#else
// Runs exclusively on Original Tracker (180 MHz Kinetis MK66)
#endif-
Gotchas with Preprocessor Guards:
-
Never use
#ifdef __MK66FX1M0__insidecore/: For legacy Teensy Audio library compatibility,core/makefiledefines-D__MK66FX1M0__in its baseDEFINESfor bothMK66andIMXbuilds. Always use#ifndef PLATFORM_IMX(or#if !defined(PLATFORM_IMX)) when writing code exclusively for the Original Tracker. -
Use
#if GUI_HANDLE_SYNTH(not#ifdef GUI_HANDLE_SYNTH): Incore/interface/core/interfaceDefs.h,GUI_HANDLE_SYNTHis always defined (1onPLATFORM_IMX,0onMK66), so#ifdef GUI_HANDLE_SYNTHwill mistakenly evaluate to true on the Original Tracker. -
Custom Build Flags (
CUSTOM_DEFINES): You can pass ad-hoc feature flags from the command line without editing makefiles viamake all CUSTOM_DEFINES="-DMY_EXPERIMENTAL_FEATURE". -
Platform-Specific
.ptfxPlugins:.ptfxSample Editor plugins are compiled once for all devices, but can restrict themselves to Tracker+ / Tracker Mini by settingPTFX_FLAG_IMX_ONLYin theirPtfxHeader::flags(editor-fx-sdk/tracker_plugin.h), or adapt dynamically at runtime by checkingchannels(1vs2) inplugin_process_block().
-
Never use
Tracker+ and Tracker Mini (PLATFORM_IMX) can expose a USB serial port that carries the firmware's log output and a small command console. Together with the existing USB storage mode, it lets a host script copy a new .ptf to the SD card and start the firmware update without touching the device or removing the card.
It is off unless you ask for it twice: the code is only compiled in with a build flag, and the port is only enumerated when the SD card is marked for development. A normal build on a normal card is unaffected.
| Switch | Where | Effect |
|---|---|---|
ENABLE_DEV_CONSOLE |
Build flag | Compiles the console (platforms/imx/source/DevConsole.cpp) and its 4 KB output buffer in SRAM_DTC. Without it the console is replaced by empty inline stubs. |
ENABLE_LOG |
Build flag | Compiles the LOG() / LOGF() call sites (core/source/log.h) at the normal -O2 optimization level. DEBUG=1 also enables them, but additionally switches to -Og and changes boot behavior. |
/.develop |
Empty file in the SD card root | Develop mode (interfaceGlobals.devMode). With ENABLE_DEV_CONSOLE, the firmware adds the serial port to its USB configuration shortly after boot. Also shows the diagnostics on the Config screen. |
# Build a Tracker Mini image with the console and logging:
make mini CUSTOM_DEFINES="-DENABLE_DEV_CONSOLE -DENABLE_LOG"The makefiles do not track compiler flags, so run make clean when switching CUSTOM_DEFINES.
#include "log.h"
LOG("sequencer stop"); // appends a newline
LOGF("sequencer play from step %d\n", fromPos); // printf-style, no newline added- Output is queued in a ring buffer and sent from the main loop, so
LOG()/LOGF()may be called from the audio interrupt. If the buffer overflows, the excess is dropped and reported as@log dropped N bytes. -
Do not format floats (
%f) from interrupt context: newlib allocates from the heap to format them. Log scaled integers there instead. - Messages logged before the host opens the port are kept (up to the buffer size) and delivered when it does, so the boot log is not lost.
The port is a plain CDC-ACM serial port (baud rate is irrelevant). The host sends one command per line, terminated by \n or \r. Every reply is a single line that starts with @; anything else on the port is log output. A reply always begins on a fresh line, even if a log message was mid-line.
| Command | Reply | Action |
|---|---|---|
ping |
@tracker-dev <mini|plus> <build id> |
Identifies the device and the running build (BUILD_ID, see make version). |
storage on / storage off
|
@ok storage on|off, or @err storage is still on|off
|
Enters or leaves Config > USB > Storage mode. Refused while the interface is not in its normal run state (for example during project load). |
flash <name> |
@ok flash pending, then the device resets; or @err ...
|
Remounts the SD card, checks that /Firmware/<name> exists, then starts the same bootloader hand-off as Config > Firmware > Firmware update. <name> is a bare filename of at most 31 characters. |
reboot |
@ok reboot pending |
Resets the MCU (and makes a Tracker Mini start again without the power button). |
help |
@ok commands: ... |
Lists the commands. |
Anything else answers @err unknown command: ...; an over-long line answers @err line too long.
A scripted deployment is therefore:
-
ping, to find the device and note the running build. -
storage on, then close the serial port. The device waits for the port to close before it re-enumerates with the storage class. - Copy the
.ptfinto/Firmware/on the mounted volume and eject it. - Reopen the port and send
flash <name>. The device resets into the bootloader, which flashes the file. - When the port reappears,
pingagain and compare the build id.
Keep the port closed when using USB storage mode from the device's own menu. While a host holds the serial port open (for example to follow the log), the device postpones the USB re-enumeration that entering or leaving storage mode needs.
Recovery: a build that fails to boot has no console. Keep a known-good
.ptfin/Firmware/and use the recessed reset button as described in the README.
Full developer reference and C++ examples live in docs/global_file_browser.md (core/interface/fileBrowser/GlobalFileBrowser.h, GlobalFileBrowser.cpp).
-
One Shared Module Across Subsystems: Covers 6 modes (
kLoadWav,kSaveWav,kLoadGenericFile,kSaveGenericFile,kLoadFolderPackage,kSaveFolderPackage), used by Project Open / Save As / MOD & IT import, Synth Patch Load / Save As & Sample Slots, Sample Editor.ptfxfile parameters, and.ptpeffect presets. The multi-selection Sample Loader intentionally remains separate. -
Non-Overlapping
24 KBScratch Allocation ([744 KB .. 768 KB]): Shares the top slice ofexternalRamScratchBuffabove.ptfxcode, working scratch, and secondary WAV buffers, preserving up to10LRU directory/cursor contexts (kMaxSavedContexts = 10) keyed bycontextKey. -
Navigation & FatFs Hygiene: Supports
Left-arrow jump-to-top in the Explorer pane, protected system folders (kProtectedFolders), inline metadata (onDescribeItem), and pad auditioning (onPadEvent). Callbacks inspecting files on cursor highlight must close FatFs handles immediately (closeFile(fh)withdeleteOnClose = true) and silence preview voices (silencePart/onPreviewStop) before loading the next asset.