speaker: play exact frequency in speaker_play_tone()

The applib speaker_play_tone() wrapper used to round its frequency_hz
argument to the nearest MIDI semitone before submitting a one-note
sequence — a 400 Hz request would actually play as G4 (392 Hz). Add a
dedicated tone path through the service and a sys_speaker_play_tone
syscall that compute phase_inc directly from the frequency, and
rewire the applib wrapper through it. The note sequencer keeps its
MIDI-only identity for melodies and tracks; tones
get their own primitive.

Bump SDK revision to 98 (minor 0x5f) to mark the behavior change.

Signed-off-by: Joshua Jun <lets@throw.rocks>

Author: jplexer

include/pbl/services/speaker/speaker_service.h

@@ -29,6 +29,7 @@ typedef enum {
   SpeakerSourceNoteSeq,
   SpeakerSourceStream,
   SpeakerSourceTracks,
+  SpeakerSourceTone,
 } SpeakerSourceType;
 
 //! Initialize the speaker service. Called once at boot.
@@ -43,6 +44,18 @@ void speaker_service_init(void);
 bool speaker_service_play_note_seq(const SpeakerNote *notes, uint32_t num_notes,
                                    SpeakerPriority pri, uint8_t vol);
 
+//! Play a single tone at an exact frequency on the speaker.
+//! @param freq_hz Tone frequency in Hz (0 = silence/rest)
+//! @param duration_ms Tone duration in milliseconds (max 10000)
+//! @param waveform Waveform to use (SpeakerWaveform value)
+//! @param velocity Per-note amplitude scale 0-127 (0 = use master volume)
+//! @param pri Priority level
+//! @param vol Volume (0-100)
+//! @return true if playback started, false if preempted by higher priority
+bool speaker_service_play_tone(uint16_t freq_hz, uint16_t duration_ms,
+                               uint8_t waveform, uint8_t velocity,
+                               SpeakerPriority pri, uint8_t vol);
+
 //! Play N monophonic tracks in parallel, mixed together.
 //! Track arrays and any sample data are copied into kernel memory.
 //! @param tracks Array of tracks. For each, its notes array and (optional)

src/fw/applib/ui/speaker.c

@@ -9,60 +9,6 @@
 #include "syscall/syscall.h"
 #include "system/logging.h"
 
-// MIDI note number for a given frequency (approximate, nearest semitone)
-// Uses: midi = 69 + 12 * log2(freq/440)
-static uint8_t prv_freq_to_midi(uint16_t freq_hz) {
-  if (freq_hz == 0) {
-    return 0;
-  }
-
-  // Simple lookup for common frequencies, otherwise approximate
-  // Using integer math: find closest MIDI note
-  // Standard: A4 = 440Hz = MIDI 69
-  // Each semitone is freq * 2^(1/12) ~= freq * 1.0595
-
-  // Binary search approach: start from A4 and adjust
-  int16_t note = 69;
-  uint32_t target = (uint32_t)freq_hz * 256;  // 8.8 fixed point
-
-  // Find the right octave and semitone using ratio comparison
-  // Semitone ratios * 1024 relative to octave base
-  static const uint16_t semitone_ratio_x1024[] = {
-    1024, 1085, 1149, 1217, 1290, 1366, 1448, 1534, 1625, 1722, 1824, 1933
-  };
-
-  // Find octave
-  uint32_t base_freq = 440 * 256;  // A4 in 8.8
-  int octave_offset = 0;
-
-  while (target >= base_freq * 2 && note < 127) {
-    base_freq *= 2;
-    octave_offset++;
-  }
-  while (target < base_freq && note > 0) {
-    base_freq /= 2;
-    octave_offset--;
-  }
-
-  // Find semitone within octave
-  int best_semi = 0;
-  uint32_t best_diff = UINT32_MAX;
-  for (int s = 0; s < 12; s++) {
-    uint32_t semi_freq = (base_freq * semitone_ratio_x1024[s]) / 1024;
-    uint32_t diff = (target > semi_freq) ? (target - semi_freq) : (semi_freq - target);
-    if (diff < best_diff) {
-      best_diff = diff;
-      best_semi = s;
-    }
-  }
-
-  note = 69 + octave_offset * 12 + best_semi;
-  if (note < 0) note = 0;
-  if (note > 127) note = 127;
-
-  return (uint8_t)note;
-}
-
 bool speaker_play_notes(const SpeakerNote *notes, uint32_t num_notes, uint8_t volume) {
   if (!notes || num_notes == 0) {
     PBL_LOG_ERR("tried to play null or empty note sequence");
@@ -78,15 +24,9 @@ bool speaker_play_tone(uint16_t frequency_hz, uint32_t duration_ms,
     duration_ms = 10000;
   }
 
-  SpeakerNote note = {
-    .midi_note = prv_freq_to_midi(frequency_hz),
-    .waveform = (uint8_t)waveform,
-    .duration_ms = (uint16_t)duration_ms,
-    .velocity = 0,  // use global volume
-    .reserved = 0,
-  };
-
-  return sys_speaker_play_note_seq(&note, 1, 0 /* SpeakerPriorityApp */, volume);
+  return sys_speaker_play_tone(frequency_hz, (uint16_t)duration_ms,
+                               (uint8_t)waveform, 0 /* use global volume */,
+                               0 /* SpeakerPriorityApp */, volume);
 }
 
 bool speaker_stream_open(SpeakerPcmFormat format, uint8_t volume) {

src/fw/process_management/pebble_process_info.h

@@ -160,9 +160,10 @@ typedef enum {
 // sdk.major:0x5 .minor:0x5c -- Add light_is_on() and expose touch_service_subscribe/unsubscribe to apps (rev 95)
 // sdk.major:0x5 .minor:0x5d -- Add app_light_set_color_rgb888() for 8-bit-per-channel backlight tint (rev 96)
 // sdk.major:0x5 .minor:0x5e -- Add Speaker API (rev 97)
+// sdk.major:0x5 .minor:0x5f -- speaker_play_tone() now plays the exact frequency (rev 98)
 
 #define PROCESS_INFO_CURRENT_SDK_VERSION_MAJOR 0x5
-#define PROCESS_INFO_CURRENT_SDK_VERSION_MINOR 0x5e
+#define PROCESS_INFO_CURRENT_SDK_VERSION_MINOR 0x5f
 
 // The first SDK to ship with 2.x APIs
 #define PROCESS_INFO_FIRST_2X_SDK_VERSION_MAJOR 0x4

src/fw/services/speaker/speaker_service.c

@@ -35,6 +35,13 @@ typedef struct {
   NoteSequenceState note_seq;
   SpeakerNote *note_buf;  // kernel_malloc'd copy of notes
 
+  // Single tone source (raw frequency, no MIDI quantization)
+  uint32_t tone_samples_remaining;
+  uint32_t tone_phase_acc;   // 16.16 fixed-point
+  uint32_t tone_phase_inc;   // per-sample phase increment
+  uint8_t tone_waveform;
+  uint8_t tone_velocity;
+
   // PCM stream source
   PcmStreamState pcm_stream;
   SpeakerPcmFormat pcm_format;
@@ -174,6 +181,9 @@ static void prv_stop_internal(SpeakerFinishReason reason) {
     pcm_stream_deinit(&s_state.pcm_stream);
   } else if (s_state.source_type == SpeakerSourceTracks) {
     prv_free_tracks();
+  } else if (s_state.source_type == SpeakerSourceTone) {
+    s_state.tone_samples_remaining = 0;
+    s_state.tone_phase_inc = 0;
   }
 
   s_state.state = SpeakerStateIdle;
@@ -330,6 +340,27 @@ static void prv_refill_bg(void *data) {
       memset(s_state.refill_buf, 0, SPEAKER_REFILL_SAMPLES * sizeof(int16_t));
       samples_generated = SPEAKER_REFILL_SAMPLES;
     }
+  } else if (s_state.source_type == SpeakerSourceTone) {
+    uint32_t to_gen = s_state.tone_samples_remaining;
+    if (to_gen > SPEAKER_REFILL_SAMPLES) {
+      to_gen = SPEAKER_REFILL_SAMPLES;
+    }
+    if (to_gen == 0) {
+      prv_stop_internal(SpeakerFinishReasonDone);
+      return;
+    }
+    if (s_state.tone_phase_inc == 0) {
+      memset(s_state.refill_buf, 0, to_gen * sizeof(int16_t));
+    } else {
+      for (uint32_t i = 0; i < to_gen; i++) {
+        s_state.refill_buf[i] = note_synth_sample(s_state.tone_waveform,
+                                                  s_state.tone_phase_acc,
+                                                  s_state.tone_velocity);
+        s_state.tone_phase_acc += s_state.tone_phase_inc;
+      }
+    }
+    s_state.tone_samples_remaining -= to_gen;
+    samples_generated = to_gen;
   } else if (s_state.source_type == SpeakerSourceTracks) {
     memset(s_state.mix_buf, 0, sizeof(int32_t) * SPEAKER_REFILL_SAMPLES);
     uint32_t max_generated = 0;
@@ -401,6 +432,41 @@ bool speaker_service_play_note_seq(const SpeakerNote *notes, uint32_t num_notes,
   return true;
 }
 
+bool speaker_service_play_tone(uint16_t freq_hz, uint16_t duration_ms,
+                               uint8_t waveform, uint8_t velocity,
+                               SpeakerPriority pri, uint8_t vol) {
+  if (!s_state.initialized || duration_ms == 0) {
+    return false;
+  }
+
+  if (!prv_can_preempt(pri)) {
+    return false;
+  }
+
+  if (s_state.state != SpeakerStateIdle) {
+    prv_stop_internal(SpeakerFinishReasonPreempted);
+  }
+
+  s_state.tone_samples_remaining =
+      ((uint32_t)duration_ms * SPEAKER_SAMPLE_RATE) / 1000;
+  s_state.tone_phase_acc = 0;
+  // phase_inc = freq_hz * 65536 / sample_rate (16.16 fixed-point per sample)
+  s_state.tone_phase_inc = (freq_hz != 0)
+      ? ((uint32_t)freq_hz * 65536u) / SPEAKER_SAMPLE_RATE : 0;
+  s_state.tone_waveform = waveform;
+  s_state.tone_velocity = velocity;
+
+  s_state.state = SpeakerStatePlaying;
+  s_state.source_type = SpeakerSourceTone;
+  s_state.priority = pri;
+  s_state.volume = vol;
+
+  prv_start_audio(vol);
+  prv_refill_bg(NULL);
+
+  return true;
+}
+
 bool speaker_service_play_tracks(const SpeakerTrack *tracks, uint32_t num_tracks,
                                  SpeakerPriority pri, uint8_t vol) {
   if (!s_state.initialized || !tracks || num_tracks == 0 ||
@@ -611,6 +677,12 @@ bool speaker_service_play_note_seq(const SpeakerNote *notes, uint32_t num_notes,
   return false;
 }
 
+bool speaker_service_play_tone(uint16_t freq_hz, uint16_t duration_ms,
+                               uint8_t waveform, uint8_t velocity,
+                               SpeakerPriority pri, uint8_t vol) {
+  return false;
+}
+
 bool speaker_service_play_tracks(const SpeakerTrack *tracks, uint32_t num_tracks,
                                  SpeakerPriority pri, uint8_t vol) {
   return false;

src/fw/syscall/syscall.h

@@ -94,6 +94,9 @@ int32_t sys_vibe_get_vibe_strength(void);
 #include "pbl/services/speaker/track.h"
 bool sys_speaker_play_note_seq(const SpeakerNote *notes, uint32_t num_notes,
                                uint8_t priority, uint8_t volume);
+bool sys_speaker_play_tone(uint16_t freq_hz, uint16_t duration_ms,
+                           uint8_t waveform, uint8_t velocity,
+                           uint8_t priority, uint8_t volume);
 bool sys_speaker_play_tracks(const SpeakerTrack *tracks, uint32_t num_tracks,
                              uint8_t priority, uint8_t volume);
 bool sys_speaker_stream_open(uint8_t priority, uint8_t volume, uint8_t format);

src/fw/syscall/syscall_speaker.c

@@ -35,6 +35,28 @@ DEFINE_SYSCALL(bool, sys_speaker_play_note_seq, const SpeakerNote *notes,
                                        (SpeakerPriority)priority, volume);
 }
 
+DEFINE_SYSCALL(bool, sys_speaker_play_tone, uint16_t freq_hz,
+               uint16_t duration_ms, uint8_t waveform, uint8_t velocity,
+               uint8_t priority, uint8_t volume) {
+  if (priority > SpeakerPriorityCritical) {
+    priority = SpeakerPriorityApp;
+  }
+
+  if (waveform >= SpeakerWaveformCount) {
+    syscall_failed();
+  }
+
+  if (velocity > 127) {
+    syscall_failed();
+  }
+
+  PebbleTask task = pebble_task_get_current();
+  speaker_service_set_owner_task(task);
+
+  return speaker_service_play_tone(freq_hz, duration_ms, waveform, velocity,
+                                   (SpeakerPriority)priority, volume);
+}
+
 DEFINE_SYSCALL(bool, sys_speaker_play_tracks, const SpeakerTrack *tracks,
                uint32_t num_tracks, uint8_t priority, uint8_t volume) {
   if (PRIVILEGE_WAS_ELEVATED) {

tools/generate_native_sdk/exported_symbols.json

@@ -4,7 +4,7 @@
               "You should also make sure you are obeying our API design guidelines:",
               "https://pebbletechnology.atlassian.net/wiki/display/DEV/SDK+API+Design+Guidelines"
             ],
-  "revision" : "97",
+  "revision" : "98",
   "version" : "2.0",
   "files": [
     "fw/drivers/ambient_light.h",