From 62217440feb352834ae8e176329d1156a360dba3 Mon Sep 17 00:00:00 2001
From: ch3 <ch3@mailbox.org>
Date: Sat, 24 Jun 2023 00:04:05 +0200
Subject: [PATCH] usermodule:bl00mbox: expose constants, start documentation
---
.../bl00mbox/buds/tinysynth/tinysynth.h | 5 +-
docs/api/bl00mbox.rst | 106 ++++++++++++++++++
docs/api/synth.rst | 14 ---
docs/index.rst | 2 +-
usermodule/mp_bl00mbox.c | 14 +++
5 files changed, 123 insertions(+), 18 deletions(-)
create mode 100644 docs/api/bl00mbox.rst
delete mode 100644 docs/api/synth.rst
diff --git a/components/bl00mbox/buds/tinysynth/tinysynth.h b/components/bl00mbox/buds/tinysynth/tinysynth.h
index aed43e16db..54d3a05fc9 100644
--- a/components/bl00mbox/buds/tinysynth/tinysynth.h
+++ b/components/bl00mbox/buds/tinysynth/tinysynth.h
@@ -7,9 +7,6 @@
#define SAMPLE_RATE 48000
-#define TRAD_OSC_DECAY_STEP 0.01
-#define TRAD_OSC_ATTACK_POP_BLOCK 16
-
#define TRAD_ENV_PHASE_OFF 0
#define TRAD_ENV_PHASE_ATTACK 1
#define TRAD_ENV_PHASE_DECAY 2
@@ -23,6 +20,8 @@
#define TRAD_OSC_WAVE_SQUARE 4
#define TRAD_OSC_WAVE_PULSE 5
#define TRAD_OSC_WAVE_BLIP 6
+#define TRAD_OSC_WAVE_NES_LONG 7
+#define TRAD_OSC_WAVE_NES_SHORT 8
typedef struct {
diff --git a/docs/api/bl00mbox.rst b/docs/api/bl00mbox.rst
new file mode 100644
index 0000000000..cd7c60d80a
--- /dev/null
+++ b/docs/api/bl00mbox.rst
@@ -0,0 +1,106 @@
+.. py:module:: bl00mbox
+
+
+``bl00mbox`` module
+===================
+
+This module provides the `tinysynth` class. With it notes can be defined and in turn played.
+
+.. py:class:: tinysynth
+
+ A `tinysynth` is defined by its pitch (in Hz), waveform (sine, triangle, ... see below) and envelope (adsr, see below).
+
+ .. py:method:: __init__(freq:int)
+
+ Create a tinysynth and provide a frequency.
+ Default values:
+ waveform: TRAD_OSC_WAVE_TRI.
+ attack: 20ms
+ decay: 500ms
+ sustain: 0
+ release: 500ms
+
+ .. py:method:: start()
+
+ Start the `tinysynth`. Essentially put it into attack phase.
+
+ .. py:method:: stop()
+
+ Stop the `tinysynth`. Essentially put it into release phase (which will be followed by the 'off phase').
+
+ .. py:method:: freq(freq)
+
+ Set the frequency of the `tinysynth` to `freq`.
+
+ .. py:method:: tone(tone)
+
+ Set semitone TODO
+
+ .. py:method:: waveform(waveform)
+
+ Set the waveform to one of :code:`TRAD_OSC_WAVE_{SINE/FAKE_SINE/TRI/SAW/SQUARE/PULSE/BLIP/NES_LONG/NES_SHORT}`. (See below.)
+
+ .. py:method:: attack(duration)
+
+ Set the attack of the `tinysynth` to `duration` in milliseconds.
+
+ .. py:method:: decay(duration)
+
+ Set the attack of the `tinysynth` to `duration` in milliseconds.
+
+ .. py:method:: release(duration)
+
+ Set the attack of the `tinysynth` to `duration` in milliseconds.
+
+ .. py:method:: sustain(level)
+
+ Set the attack of the `tinysynth` to `level`.
+ TODO what is the valid value range, what does it represent?
+
+ .. py:method:: volume(volume)
+
+ Set the attack of the `tinysynth` to `volume`.
+ TODO details!
+
+ .. py:method:: __del__()
+
+ Deletes the `tinysynth`.
+
+
+Event Phase Constants
+---------------------
+
+The phases a particular `tinysynth` can be in.
+
+(ATTACK -> DECAY -> SUSTAIN -> RELEASE)
+
+.. py:data:: TRAD_ENV_PHASE_OFF
+.. py:data:: TRAD_ENV_PHASE_ATTACK
+.. py:data:: TRAD_ENV_PHASE_DECAY
+.. py:data:: TRAD_ENV_PHASE_SUSTAIN
+.. py:data:: TRAD_ENV_PHASE_RELEASE
+
+Wave Form Constants
+-------------------
+
+.. py:data:: TRAD_OSC_WAVE_SINE
+.. py:data:: TRAD_OSC_WAVE_FAKE_SINE
+.. py:data:: TRAD_OSC_WAVE_TRI
+.. py:data:: TRAD_OSC_WAVE_SAW
+.. py:data:: TRAD_OSC_WAVE_SQUARE
+.. py:data:: TRAD_OSC_WAVE_PULSE
+.. py:data:: TRAD_OSC_WAVE_BLIP
+.. py:data:: TRAD_OSC_WAVE_NES_LONG
+.. py:data:: TRAD_OSC_WAVE_NES_SHORT
+
+
+Example Usage
+-------------
+
+.. code-block:: python
+
+ import bl00mbox
+ s = bl00mbox.tinysynth(440)
+ s.start()
+ s.stop()
+
diff --git a/docs/api/synth.rst b/docs/api/synth.rst
deleted file mode 100644
index eaae62fb9a..0000000000
--- a/docs/api/synth.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-.. py:module:: synth
-
-``synth`` module
-================
-
-.. py:class:: tinysynth
-
- .. py:method:: start
- .. py:method:: stop
- .. py:method:: freq
- .. py:method:: tone
- .. py:method:: waveform
- .. py:method:: attack
- .. py:method:: decay
diff --git a/docs/index.rst b/docs/index.rst
index 7f9ccbd053..d6d70c7df5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,7 +22,7 @@ Welcome to flow3r's documentation!
api/badge_link.rst
api/hardware.rst
api/kernel.rst
- api/synth.rst
+ api/bl00mbox.rst
api/ctx.rst
diff --git a/usermodule/mp_bl00mbox.c b/usermodule/mp_bl00mbox.c
index 9b492e4d2c..08df59aa42 100644
--- a/usermodule/mp_bl00mbox.c
+++ b/usermodule/mp_bl00mbox.c
@@ -136,6 +136,20 @@ STATIC const mp_rom_map_elem_t tinysynth_locals_dict_table[] = {
{ MP_ROM_QSTR(MP_QSTR_sustain), MP_ROM_PTR(&tinysynth_sustain_obj) },
{ MP_ROM_QSTR(MP_QSTR_release_ms), MP_ROM_PTR(&tinysynth_release_ms_obj) },
{ MP_ROM_QSTR(MP_QSTR___del__), MP_ROM_PTR(&tinysynth_deinit_obj) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_ENV_PHASE_OFF), MP_ROM_INT(TRAD_ENV_PHASE_OFF) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_ENV_PHASE_ATTACK), MP_ROM_INT(TRAD_ENV_PHASE_ATTACK) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_ENV_PHASE_DECAY), MP_ROM_INT(TRAD_ENV_PHASE_DECAY) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_ENV_PHASE_SUSTAIN), MP_ROM_INT(TRAD_ENV_PHASE_SUSTAIN) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_ENV_PHASE_RELEASE), MP_ROM_INT(TRAD_ENV_PHASE_RELEASE) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_SINE ), MP_ROM_INT(TRAD_OSC_WAVE_SINE ) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_FAKE_SINE ), MP_ROM_INT(TRAD_OSC_WAVE_FAKE_SINE ) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_TRI ), MP_ROM_INT(TRAD_OSC_WAVE_TRI ) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_SAW ), MP_ROM_INT(TRAD_OSC_WAVE_SAW ) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_SQUARE ), MP_ROM_INT(TRAD_OSC_WAVE_SQUARE ) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_PULSE ), MP_ROM_INT(TRAD_OSC_WAVE_PULSE ) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_BLIP ), MP_ROM_INT(TRAD_OSC_WAVE_BLIP ) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_NES_LONG ), MP_ROM_INT(TRAD_OSC_WAVE_NES_LONG ) },
+ { MP_ROM_QSTR(MP_QSTR_TRAD_OSC_WAVE_NES_SHORT ), MP_ROM_INT(TRAD_OSC_WAVE_NES_SHORT ) },
};
STATIC MP_DEFINE_CONST_DICT(tinysynth_locals_dict, tinysynth_locals_dict_table);
--
GitLab