usermodule:bl00mbox: expose constants, start documentation

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 {

docs/api/bl00mbox.rst

+.. 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()
+

docs/api/synth.rst

-.. 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

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
 
 

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);