README pulses

  Copyright © Robert Epprecht  www.RobertEpprecht.ch   GPLv2
  http://github.com/reppr/pulses


  ESP32 based MUSICAL INSTRUMENTS and esp-now synchronised ORCHESTRA
  producing and playing harmonical patterns as MUSIC and COLOUR patterns

  The instruments will be used for performaces
  and interactive sound/light/colour installations during
  "The Living Room Festival 2019", STADIONBRACHE Zürich, Switzerland, august 24 - 31
  see: https://www.facebook.com/livingroomstadionbrache/


  Portable instruments
    have a *touch MORSE input* pin for configuration
    can react interactively on MOVEMENT using MPU6050
    so, when the players DANCE, the music will change in the rhythm of the dance ;)

  Stationary instruments
    some need more electrical power
    like RGB strings
    or LED spots

  Configure all instruments (from any one of them) using a menu interface and ESP-NOW:
   * either by using MORSE TOUCH input
   * or using a serial connection to one instrument

  The configuration can be sent to the recipient(s)  by esp_now_send() 'C<...>'
    'CC<n>' to set recipient(s)
    'C<xyz>' sends '<xyz>' to the selected recipent(s)

  Start the band with menu 'CP' (from *any* instrument in the group)



  (the rest of this README is *very outdated* and *very* incomplete, sorry)

  ****************************************************************
  old README:

  Arduino library collection to raise actions in harmonical time intervals.
  Periodically do multiple independent tasks named 'pulses'.

  some pulses can contol hardware pins
  i call them 'click' pulses
  if you hang piezzos on them you'll hear them click, or making sounds

  Pulses can do many other things
  like starting other pulses
  playing patterns
  sweeping
  give infos.

  and yes, they can also blink a LED :)
  many LEDs in synchronised patterns, btw

  during that other program functions continue to run
  *if* there are the ressources

  main program is
  libraries/Pulses/examples/pulses/pulses.ino	heavy development

  * library 'Pulses'	daily used
  * library 'Menu'	quite usable, see below
  * library 'Inputs'	experimental state, working, but not used recently 
  * library 'Harmonics' in statu nascendi
  * 'softboard'	Arduino software breadbord, see below


  (for Menu library and softboard see below)

************************************************************
****************	Harmonicality	    ****************
************************************************************

Pulses is a harmonical experiment
running on ESP8266 NodeMCU and ARDUINO (Mega, Due) boards.

It explores analogies in topics like music, mathematics, aesthetics,
just to name a few.


I use the terms 'harmonical' or 'harmonicality' in a broader sense,
not restricted to the musical scope. 

I am talking about the implications of selected simple integer relationships
in mathematics and aesthetics, music, physics, numerics, mythology, art.

I'm not aware of any English term for that, German 'Harmonik' comes close,
	see i.e.  https://de.wikipedia.org/wiki/Hans_Kayser#Harmonik



In music a chord uses certain selected tones fitting aesthetically.
If we look at the frequencies we see *simple* rational number relationships,
frequeny relationships like 4:5:6 or 2:3:4:5

So what?
Can we hear numbers?

How is our aesthetic perception connected with mathematics, with numerics?



If I say 'harmonical experiment' I mean things like the following:

Thinking about musical chords we have tones vibrating in mathematical order.
While one makes 2 waves another makes 3, exactly.
If not, we hear that. They get out of tune.

If we take faster vibrations, keeping the exact relationship between them,
the chord gets higher.

Slowing it down it will produce bass notes, deeper and deeper
until we can hear the individual clicks rumble
somewhere between bass and rhythm.

With slow vibrations we get rhythms.
hmm?

interesting


Tuning the drums of the rhythm to a short note in the original pitch
while the drum keeps beating slow,  in a very low octave of the same note
we get fascinating melody patterns, chord progressions,
fractal-like structures.


What rhythm, what melody patterns match a minor chord?
a pentatonic scale? a chord progression?

Or the other way round: How do the numbers sound together?


That's the kind of questions pulses gives an instrument to try and play with.

I hope some will have fun with it :)

****************************************************************
****************************************************************


Libraries:
****************************************************************
Already quite usable:

* The Menu library.

  A Menu can be used to interact with your Arduino sketch over a stream interface
  like Serial. So you could send commands (mostly one letter tokens) and numbers
  from your computer over USBserial and let it trigger sketch functions, set
  variables, get informations back over USBserial and the like.

  As exact timing will be crucial to the pulses project the Menu class is
  implemented in a way that it will never block program flow any longer then
  necessary. I call this 'run-through-technique'. The menu returns immediately
  if it has nothing to do, on input collecting a single byte of input a time
  until it receives an 'end token'.

  The menu will never delay unless *you* program an action that does that,
  and tell the menu to trigger it ;)

  Menu has support for multiple menu pages and 'visability groups' that make
  pages be active for a group of pages, even if only one of them is visible.

  More documentation planed after using and developping it for a while.
  Ask if you need it now...

  Please see the examples for how to do use it.
  The source is also full of comments meant to be useful, please read.



****************************************************************
* Softboard

README softboard

   softboard  http://github.com/reppr/pulses

   Arduino hardware/software developing/testing tool.

   This version is implemented as an example for the Menu library.
   Using a library makes it easy to include in your own sketches.
   You can add more menu pages with other functionality to your sketch.


Description

   Softboard is a kind of an Arduino software breadboard.

   Simple Arduino hardware Menu interface over a serial line like USBserial.
   Softboard gives you an interface to the Arduino hardware
   by sending simple commands:
   * show infos about arduino pins and RAM usage
   * set pin mode
   * write pin states
   * read analog and digital inputs
   * write PWM values
   * continuously display changes on analog or digital inputs as bar graph
   * play analog readings back as the pitch of a tone


   Use it to test hardware like sensors, motors, things you want
   to run quick tests after setting something up on a (real) breadboard.

   Then you can use it to test software parts of your program while
   you write it and fit parts together.

   Later, when everything is working you can throw out the Menu code
   from your sketch, or keep it as an interface to your program.


   Send a sequence of one letter commands and numeric chiffres
   followed by a linebreak over a serial line (say from your computer)
   to the arduino to trigger menu actions and get infos.

   The arduino will buffer serial input byte by byte (without waiting)
   until a terminating linefeed is received as an end token.
   Any sequence of one or more '\n'  '\c'  '\0' is accepted as end token.


   Commands can read and set I/O pin configuration and states,
   switch pins on/off, read and write digital and analog values,
   switch pullup/high-z, continuously watch changing inputs over time.
   You can also connect a piezzo to a spare digital pin and listen
   to the changes on an analog input coded as pitch of a tone.


   Send '?' (and a linefeed) over serial line to see the menu.
   It displays some basic infos and shows some one-letter commands.


'run-through' cpu time friendly implementation:

   Softboard tries not to block the processor longer then needed and
   to let as much cpu time as possible to any other code possibly running.
   Menu will just run through it's code and return immediately.


Integrate your own code:

   It is easy to define Menu pages as an interface to your own code.
   Please have a look at the Menu/examples/ to see how to do this.

   You can define multiple Menu pages and define visability groups
   for pages sharing the same commands.

   Softboard is just a definition of a Menu page, you can add pages
   or delete them when compiling your program as you like.


Installation:

   Get it from http://github.com/reppr/pulses
   Put contents of the pulses/libraries/ folder into sketchbook/libraries/

   Softboard is implemented as an example of libraries/Menu/
   After a restart the Arduino GUI shows softboard under
   File >> Sketchbook >> libraries >> Menu >> softboard

	Arduino versions older than 1.0 need a fix:
	  see this thread:
	  http://code.google.com/p/arduino/issues/detail?id=604&start=200

	    short version (adapt to your arduino version)
	      edit file arduino-0022/hardware/arduino/cores/arduino/wiring.h
	      comment out line 79 (round macro)
	      #define round(x)     ((x)>=0?(long)((x)+0.5):(long)((x)-0.5))
	      tested on arduino-0023

	For older arduino versions you also have to rename the sketch file
	from softboard.ino to softboard.pde


How it works:

   You communicate with the arduino over a serial connection
   that could be a real serial line or an usb cable.
   The library should be able to deal with other stream interfaces, btw.

   The minimalistic menu shows you one letter commands and listens to
   your input. Serial inputs are buffered until you send a linefeed.
   Then your inputs (commands and numbers as sequences of chiffres)
   will be read and acted upon.


Configure your terminal program:

   Do configure your terminal emulation program to send some sort of
   line ending code, usual culprits should work.

   Set arduino baud rate by editing the line starting with
   #define BAUDRATE in softboard.ino
   and set it to the same value in your terminal software.

   So if for example you use the Arduino 'Serial Monitor' window
   check that it *does* send 'Newline' (in the bottom window frame)
   and set baud rate to the same value as BAUDRATE on the arduino.


   Send '?' (and a linefeed) over serial line to see the menu.
   It displays some basic infos and shows some one-letter commands.

   'e' toggle serial echo.
   'x' toggle visibility of analog inputs as extra digital I/O pins.



Some examples:

       Always let your terminal send a linefeed after the example string
       to trigger the menu actions.

       Spaces in the strings can be omitted.



   Example 1:  'D13 OH' switch LED on   (D select pin, O output, H high)
               'L'      off again       (L low)


   Example 2:  writing high to an input activates internal pullup resistor

	       'D13 IH' pullup LED pin  (D select pin, I input, H high)

                                        LED glows at low level
               'O'      LED as OUTPUT   now the LED is on


   Example 3:  Watch an analog input like a VU meter, changing over time.
               See electric noise on unconnected floating A0 input
               scrolling over your serial terminal.
               (Touch the input if there is no visible signal.)

               Or connect a sensor to the input and explore its data...

               'A0 v'      A=select pin (both analog or digital)
                           v=display analog read values and bar graphs

			   Stop it by pressing 'v' again.


*A0	77	*****
*A0	63	****
*A0	74	*****
*A0	84	******
*A0	115	********
*A0	165	***********
*A0	237	***************
*A0	289	*******************
*A0	285	******************
*A0	241	****************
*A0	159	**********
*A0	97	*******
*A0	70	*****
*A0	63	****
*A0	76	*****
*A0	86	******
*A0	123	********
*A0	171	***********
*A0	248	****************
*A0	294	*******************
*A0	280	******************
*A0	227	***************
*A0	144	**********
*A0	87	******
*A0	66	*****



   Example 4:  Listen to an analog input value changing the pitch of a piezzo tone.
   	       This example does a similar thing as #3 playing an analog value back
	       as the pitch of a sound on a Piezzo connected from pin 8 to ground:

   	       'A0 T8'	Select analog input and the pin for the piezzo.
	       't'	toggles the tone on and off.

	       You will hear a sound on the piezzo now. The pitch will change
	       according to the reading on the analog pin.


   Example 5:  ','  Display snapshot values of all analog inputs.

                        [fixed font only]

pin     value   |                               |                               |
*A0     609     ***************************************
 A1     504     ********************************
 A2     451     *****************************
 A3     398     *************************
 A4     383     ************************
 A5     409     **************************



   Example 6:  '.'  Info on all digital pin's I/O configuration and state.

 pin 0	I  floating
 pin 1	I  floating
 pin 2	O  LOW
 pin 3	O  HIGH
 pin 4	I  floating
*pin 5	I  pullup       // * indicates the selected pin
 pin 6	I  floating
 pin 7	I  floating
 pin 8	I  floating
 pin 9	I  floating
 pin 10	I  floating
 pin 11	I  floating
 pin 12	I  floating
 pin 13	I  floating

   btw: The example output was generated after 'D2OLD3OHD5IH'.
        'D2OL D3OH D5IH' is the same, but easier to read.



   Copyright © Robert Epprecht  www.RobertEpprecht.ch   GPLv2

   http://github.com/reppr/pulses

****************************************************************