Doc updates

README.md

@@ -15,7 +15,7 @@ Linux libraries. If you _then_ modify the code, it should be still be direct com
 however, you generate the CPP on, say, a Mac, you MAY not get code that is easily compilable on the Stratus.
 
 ## Installation
-Download the [latest version of the SDK bundle](../../releases/download/v0.3.0/faust-stratus-v0.3.0.zip) to your local computer 
+Download the [latest version of the SDK bundle](../../releases/download/v0.4.0/faust-stratus-v0.4.0.zip) to your local computer 
 (NOT the Stratus pedal) and un-zip it into a folder of your choosing.
 
 You can install this SDK in either of two places - or both!
@@ -34,7 +34,68 @@ You can install this SDK in either of two places - or both!
 
 ## Usage
 
-### Design in Faust
+The usage is based on a few principles:
+
+* Faust has good patterns for integrating `faust2something` scripts - we exploit that to the full.
+* There are simple effects and complex effects - simple effects can generally be fully described in Faust and built for use with the Stratus
+  without any complications. Complex effects may require "tweaking" the CPP code generated by the Faust compiler before they are fully
+  compatible with the Stratus. This toolkit allows for both scenarios, but, obviously, the latter requires more knowledge and intervention
+  from the effect designer.
+* "Local" development - i.e. building and testing effects on your "normal" computer is a great way to speed up the development cycle. For that
+  the toolkit allows you to pass arbitrary sound sources through your effect and hear the results without having to load up the effect
+  on the Stratus itself.
+* On the other hand, once you are happy, you really do want your effect compiled and installed on the Stratus with the minimum of fuss. The
+  toolkit facilitates that too.
+
+### The `faust2stratus` command
+As part of _both_ installation routes, a command named `faust2stratus` is installed into the Faust binary folder. This is the core of getting
+your DSPs compiled for the Stratus.
+
+The basic command line invocation is as follows:
+
+```
+faust2stratus <the location of your DSP file>
+```
+
+This will take your DSP file and
+
+* Invoke the `Faust` command with the correct options for the compiler to generate CPP code suitable for use in the Stratus
+* Compile that CPP code for the platform upon which the command is being executed, generating a shared library that implements the 
+  Stratus binary interface.
+* Save the CPP file and the shared library in the folder from which the originating DSP file was read
+
+If you run that on your "normal" computer, you will end up with a shared library that can be tested using the Python wrapper that
+was also installed by the installation process. _But that shared library will not work on the Stratus_.
+
+If, however, you run that on Stratus, you will end up with a shared library that DOES work on the stratus and can be loaded by the
+Stratus engine as an effect library.
+
+#### Options
+The `faust2stratus` command has a number of Stratus-specific options that you cann add on the command line:
+
+* **-nocppc** - this will skip the CPP compile step, only generating the Stratus-compatible CPP code.
+* **-stratusinstall** - IF the build is happening on the Stratus itself, _and_ you have followed the guidelines for DSP file structure
+  described below, then the script will take the generated shared library and install it into the correct place under the correct
+  name for immediate use in the STratus. If you are currently using the effect in the active effects chain of the Stratus, you will 
+  be alerted to this by the Stratus itself going through a short upgrade cycle accompanied by the standard flashing lights.
+
+Apart from these otions, you can add any other Faust options to the command line. This may be interesting if you are experimenting
+with different CPP code generation strategies that may suite you code better (e.g. improved vectorization).
+
+Finally, you can affect the CPP compile itself by adding CPP compiler options to the `CXXOPTIONS` environment variable before
+running the command.
+
+### The `stratus-build-effect` command
+The `stratus-build-effect` command is simply a wrapper for the `faust2stratus` command that executes `faust2startus` on your Stratus
+pedal from your normal computer. It accepts all the same arguments as `faust2stratus` as described above.
+
+To use this command you must:
+
+* Have installed the toolkit on the Stratus (`install-stratus`)
+* Know the root password of the Stratus (if you installed the toolkit, you already know that)
+* Have your Stratus connected to your normal computer via USB when you execute the command.
+
+### Designing Effects in Faust
 Obviously, since this is a toolkit to get Faust-designed effect algorithms working on the Chaos Stratus
 pedal with as little fuss as possible, your gonna have to design your effect algorithm in Faust.
 
@@ -149,17 +210,15 @@ where you originally unzipped this toolkit) and build away!
 
 ### Building
 
-There are two modes of building - "Classic" and "Embedded". Embedded
-will, HOPEFULLY become _the_ way one day - because it involves installing all the tools
-on the Stratus, and, of course, since THAT is possible (and they don't take up much space) there is
-no reason why they shouldn't become part of the default firmware in the future. For now, though, it
-is separate - and I bear no responsibility if you break your Stratus!
+As discussed above, building an effect is based around the `faust2stratus` command installed
+wherever you need to build your effect.
+
+But, given that, we can roughly divide the subject of building into two modes - "Classic" and "Embedded".
 
-### Classic mode
-Classic mode means you ran `install-local` but didn't run `install-stratus` - OK, that's up to you, you
-don't wanna take risks, I understand!
+#### Classic mode
+Classic mode means you ran `install-local` but didn't (necessarily) run `install-stratus`.
 
-Actually "Classic" mode is perfectly appropriate, especially if your algorithm, as generated by 
+"Classic" mode is perfectly appropriate, especially if your algorithm, as generated by 
 the Faust compiler, isn't exactly what you want - i.e. you need to tweak the C++ code.
 
 Whatever your reasons, this is the workflow for classic mode (remembering that it implies that
@@ -168,7 +227,7 @@ you have Faust installed on your computer):
 * Generate the full C++ code using the Faust compiler:
 
    ```
-   faust2Stratus [path to your DSP file] <any other options for the Faust compiler>
+   faust2Stratus [path to your DSP file] -nocppc <any optional flags for the Faust compiler>
    ```
 
 * Massage the algorithm in the generated C++ code at will if you need to
@@ -184,33 +243,27 @@ you have Faust installed on your computer):
   for a while - _don't panic_ - that's a good sign - it's updating your current chain to use the
   new effect library!
 
-**NOTE** that the default Faust compiler options are perfectly appropriate - allowing you to add options
-is a nice flexibility feature but for most use cases unnecessary.
-
-If you have C++ build tools installed on your local computer, you will also get a shared library generated 
-that can be used on your local computer - which is actually pretty useful for _testing_ your effect without 
-having to install it to the pedal.
+If you have C++ build tools installed on your local computer, you can also get a shared library generated 
+that can be used on your local computer - which is useful for _testing_ your effect without 
+having to install it to the pedal. To do that, omit the `-nocppc` option from the `faust2stratus` command line.
 
 See [below](#using-the-python-wrapper) for usage notes.
 
-### Embedded mode
+#### Embedded mode
 
-Embedded mode means you don't need Faust or build tools on your computer - everything is on the Stratus. If you
-trust us, this is the easiest mode - but it doesn't allow you to modify the C++ code generated by the
+Embedded mode means you don't need Faust or build tools on your computer - everything is on the Stratus. 
+This is the easiest mode - but it doesn't easily allow you to modify the C++ code generated by the
 Faust compiler before that is compiled and, optionally, installed
 
 To recap, you now have a DSP file on your local computer. Since you have installed the SDK on the Stratus, 
 all you need to do to get the effect implementation onto the stratus, AND to get local backups of the 
 artifacts generated by the build process, is to run the command:
-²
+
 ```
-stratus-build-effect <the-location-of-your-DSP-file> <any other options for the Faust compiler>
+stratus-build-effect <the-location-of-your-DSP-file> <any optional options for the Faust compiler>
 ```
 
-**NOTE** that the default Faust compiler options are perfectly appropriate - allowing you to add options
-is a nice flexibility feature but for most use cases unnecessary.
-
-Again, you'll need to have the Stratus connected to the computer by USB, and you'll need to 
+You'll need to have the Stratus connected to the computer by USB, and you'll need to 
 enter the Stratus password when prompted.
 
 If THAT works, you'll end up with a C++ file and a shared library object in the same
@@ -226,10 +279,10 @@ At this point you need to follow the installation steps set out for Classic mode
 
 * You have followed the Stratus design principles (introduced above) in your DSP file (hint:
   particularly the `declare`s)
-* _and_ you run the `./sdk-build-effect` command like THIS:
+* _and_ you run the `sdk-build-effect` command like THIS:
 
   ```
-  ./sdk-build-effect <the-location-of-your-DSP-file> -stratusinstall <any other options for the Faust compiler>
+  ./sdk-build-effect <the-location-of-your-DSP-file> -stratusinstall <any optional options for the Faust compiler>
   ```
 
 If you do _that_ then you are home free - the effect will be installed in the proper folder with a proper