Coyote-1TM User’s Manual
Version 1.1
August 20, 2008
WARRANTY
OpenStomp™ warrants the Coyote-1 against defects in materials and workmanship for a period of 60
days from receipt of product. If you discover a defect, OpenStomp™. will, at its option, repair or replace
the merchandise, or refund the purchase price. Before returning the product to OpenStomp™, call for a
Return Merchandise Authorization (RMA) number. Write the RMA number on the outside of the box
used to return the merchandise to OpenStomp™. Please enclose the following along with the returned
merchandise: your name, telephone number, shipping address, and a description of the problem.
COPYRIGHTS AND TRADMEARKS
This documentation is copyright © 2008 by Eric Moyer. By downloading or obtaining a printed copy of
this documentation you agree that it is to be used exclusively with OpenStomp™ products. Any other
uses are not permitted and may represent a violation of OpenStomp™ copyrights, legally punishable
according to Federal copyright or intellectual property laws. Any duplication of this documentation for
commercial uses is expressly prohibited by OpenStomp™.
DISCLAIMER OF LIABILITY
Eric Moyer and OpenStomp™ are not responsible for special, incidental, or consequential damages
resulting from any breach of warranty, or under any legal theory, including lost profits, downtime,
goodwill, damage to or replacement of equipment or property, or any costs of recovering,
reprogramming, or reproducing any data stored in or used with OpenStomp™ products. Eric Moyer and
OpenStomp™ are also not responsible for any personal damage, including that to life and health,
resulting from use of any of our products. You take full responsibility for your OpenStomp™ application,
no matter how life-threatening it may be.
Dedication
This project is dedicated to the memory of my dear friend Larry Altneu, who died immediately after
crossing the finish line in the 2007 Orange County Marathon.
Larry was a terrific mentor. He significantly shaped the Engineer I am today, and introduced me to many
of the people involved in manufacturing this device. Hardly a week goes by that I don’t use some
Engineering trick I learned from him.
Engineers tend to live in the future. We make long term plans, dream new things, and force them into
existence. When this world occasionally reminds us that we are not in control,
it comes as a bit of a shock.
Thanks
First of all, I have to thank my awesome wife Krisula for sticking by me. This project cut into my free
time in a major way for the greater part of a year. She knew it was something I just had to do, and she
supported me all the way.
A huge thanks to Steve Wozniak, both for creating the Apple computer and for writing the book “iWoz”.
I had the audio version of iWoz playing in my car the night I conceived the Coyote-1 and it was
instrumental in inspiring me. Whenever this project lost momentum I’d start listening to iWoz again and
it would fire me back up. Now that I’m done I’ve listened to that book at least ten times. It still gets me
pumped to make stuff.
Revision History
1.0
1.1
Aug 7, 2008
Aug 20, 2008
Initial Release
Add Expansion Port Section
Elaborate on Control Socket Value to Time Conversions
Table of Contents
Chapter 1
Introduction ................................................................................................................8
Chapter 2
Licensing Summary ......................................................................................................9
Chapter 3
Recommended Reading ............................................................................................. 10
Propeller Documentation ....................................................................................................................... 10
Propeller Information ............................................................................................................................. 10
Digital Signal Processing.......................................................................................................................... 10
Chapter 4
Recommended Tools.................................................................................................. 11
Chapter 5
Software Installation.................................................................................................. 12
Chapter 6
Overview ................................................................................................................... 13
Chapter 7
Using the Pedal .......................................................................................................... 14
Connecting Equipment ........................................................................................................................... 14
Boot ......................................................................................................................................................... 15
Controlling a Patch: Knobs ..................................................................................................................... 15
Controlling a Patch: Buttons .................................................................................................................. 15
Switching Patches ................................................................................................................................... 16
Reformatting the EEPROM...................................................................................................................... 16
Patch / Module Load Errors .................................................................................................................... 16
Real Time Error: Output Clipping ............................................................................................................ 17
Real Time Error: Time Overflow.............................................................................................................. 17
Chapter 8
Restoring the Factory Configuration ........................................................................... 18
Chapter 9
Using OpenStompTM Workbench ................................................................................ 20
Connecting to the Coyote-1 .................................................................................................................... 20
System Resources ................................................................................................................................... 21
Knobs................................................................................................................................................... 21
Buttons ................................................................................................................................................ 21
LEDs ..................................................................................................................................................... 21
Audio ................................................................................................................................................... 22
Gain ..................................................................................................................................................... 22
Loading a Patch ....................................................................................................................................... 22
Working in the Editor .............................................................................................................................. 22
Zoom and Pan ..................................................................................................................................... 22
Moving Objects ................................................................................................................................... 22
Adding Effects to a Patch .................................................................................................................... 23
Connecting Objects ............................................................................................................................. 23
Modifying Static Assignments ............................................................................................................. 24
Main Menu Commands .......................................................................................................................... 24
Module List Menu Commands ................................................................................................................ 25
Patch List Menu Commands ................................................................................................................... 25
Conduit Routing Restrictions .................................................................................................................. 26
Chapter 10
Under the Hood ......................................................................................................... 27
Block Diagram ......................................................................................................................................... 27
Software Architecture ............................................................................................................................. 28
Propeller Pin Assignments ...................................................................................................................... 29
MEMBUS Interface.................................................................................................................................. 29
PLD Register: CCR (CODEC Control Register) .......................................................................................... 29
PLD Register: GPIO0 (General Purpose I/O 0)......................................................................................... 30
Chapter 11
Creating Custom Effects Modules ............................................................................... 31
Socket Types ........................................................................................................................................... 32
The Module Descriptor ........................................................................................................................... 32
A Word about Socket Ranges.................................................................................................................. 33
The Module Code .................................................................................................................................... 33
Pointer Loading ................................................................................................................................... 34
Initialization......................................................................................................................................... 34
The Synchronization Loop ................................................................................................................... 34
The Bypass Block ................................................................................................................................. 35
Effect Processing ................................................................................................................................. 35
Data Declaration ................................................................................................................................. 35
The Effects Module Creation Process ..................................................................................................... 35
Linking an Effect Module as a Static Module .......................................................................................... 36
Recompiling and Loading the O/S ........................................................................................................... 36
Useful Coyote-1 Control Socket Value to Time Conversions .................................................................. 37
Chapter 12
Working with the Expansion Port ............................................................................... 39
Overview ................................................................................................................................................. 39
Software Paradigm.................................................................................................................................. 39
Tips .......................................................................................................................................................... 39
On the remote board .......................................................................................................................... 39
On the Coyote-1 .................................................................................................................................. 40
Chapter 13
Error Codes ................................................................................................................ 41
Chapter 14
Glossary of Terms ...................................................................................................... 42
Chapter 15
Module Descriptor format.......................................................................................... 43
Chapter 16
Module Signature Format .......................................................................................... 44
Chapter 17
Module Control Block format ..................................................................................... 46
Chapter 18
Epilogue .................................................................................................................... 47
Chapter 1
Introduction
$DO || ! $DO ; try
try: command not found
- jma5t3r_y
Chapter 1 Introduction
Welcome to my crazy little world. Thanks for joining me.
You have in your hands the product of many late nights, much day dreaming, some speculative
hunches, a surprisingly large volume of caffeine, and a willingness to take some risks. If I’d known quite
how much work it would be I might not have started, but by the time I realized what I’d gotten into it
was already far too late to quit. I hope you enjoy it as much as I do. Personally, I think it’s pretty darn
cool.
Like many of you, I’ve dreamed about the possibility of an open source audio effects processor for a
long time. A lot of different things kept me from starting until the day I thought of creating one around
the Propeller processor, and that idea was so intriguing it dragged me kicking and screaming through
just over a year of design. I really had no choice. I just had to do it.
8
Chapter 2
Licensing Summary
The Coyote-1 project consists of many different assets, released under a mix of different licensing
arrangements. The following is a summary of the release licenses:
Asset
Coyote-1 O/S Source Code
Coyote-1 Effects Modules Source
Code (and associated Dynamic
Modules files (*.c1m))
Coyote-1 Schematics (and
associated Printed Circuit Board)
Coyote-1 User Manual
Open Stomp™ Workbench
Source
Open
Open
Provided
Provided
Closed
Patches
N/A
Coyote-1 Hardware
N/A
License
GPL 3
GPL 3
Copyright. Reproduction & Redistribution
Prohibited.
Copyright. Reproduction & Redistribution
Prohibited.
Copyright. Reproduction & Redistribution
Prohibited.
Creative Commons 3.0 Attribution Noncommercial (by-nc)
Copyright. Reproduction & Redistribution
Prohibited.
Chapter 2 Licensing Summary
This list is for reference purposes only. The licensing arrangements for each asset are declared on or within the assets.
9
Chapter 3
Recommended Reading
Propeller Documentation
The Propeller Manual
Describes the architecture and operation of the Propeller chip, the use of the Propeller Tool (i.e.
the Propeller IDE), the SPIN language, and the Propeller Assembly language. Avalable from the
the “Help” menu within the Propeller tool, or from Parallax’s website www.parallax.com .
Propeller Information
The Propeller Forum
Parallax maintains a forum for the Propeller chip here:
http://forums.parallax.com/forums/default.aspx?f=25
deSilva's Machine Language Tutorial
A growing reference of information about programming the Propeller in assembly language.
The document is maintained on the forums here:
http://forums.parallax.com/forums/default.aspx?f=25&m=209237
Programming resources
A collection of various Propeller Programming resources is maintained on the forums here:
http://forums.parallax.com/forums/default.aspx?f=25&m=204210
Digital Signal Processing
Chapter 3 Recommended Reading
General Introduction
A pretty good and not overly mathematical introduction to DSP can be found here:
http://www.dsptutor.freeuk.com/
10
Chapter 4
Recommended Tools
PASD (Propeller Assembly Sourcecode Debugger)
PASD is a fantastic source level debugger tool for Propeller assembly code, written by Andy
Schenk. Around August of 2007 I realized that a source level assembly debugger would be
immensely useful to Coyote-1 effect authors. I trolled around the Parallax forums to see what
people thought, and it turned out Andy had already written one, but the manual was in German
and he was waiting to get an English translation before releasing PASD to the public. I ended up
writing the English manual translation for him and the rest is history.
A copy is included on the Coyote-1 distribution CD, and the project is maintained here:
http://www.insonix.ch/propeller/prop_pasd.html
HAM (Hydra Asset Manager)
HAM is a clever and handy tool written by Richard Benson for the Propeller based Hydra video
game system to support loading and archiving data stored in the (typically unused) upper 96K of
the Hydra’s 128K EEPROM. Because the Coyote-1 also uses a 128K EEPROM, and uses the same
pins for video as the Hydra, HAM will run on the Coyote-1 and can be used to archive/restore a
“snapshot” of the entire OS, the stored patches, and stored dynamic modules (see Chapter 8).
A copy is included on the Coyote-1 distribution CD, and the project is maintained here:
http://forums.parallax.com/forums/default.aspx?f=33&p=1&m=168490
GEAR
GEAR is a cool Propeller chip emulator written by Robert Vandiver. There are a couple of times
when I got completely stuck because I couldn’t figure out what my code was doing. I was able
to throw the offending snippets into GEAR, single step them, and figure out what was really
going on.
Chapter 4 Recommended Tools
A copy is included on the Coyote-1 distribution CD, and the project is maintained here:
http://forums.parallax.com/forums/default.aspx?f=25&m=164602
11
Chapter 5
Software Installation
Chapter 5 Software Installation
1. Copy the contents of the Coyote-1 CD to a directory on your hard drive (such as C:\Coyote1).
The remaining steps are written assuming a “C:\Coyote1” installation.
2. Install the “Propeller Tool” software by running its installer (Located in
C:\Coyote1\PropellerTool\”). When prompted check “Automatically install/update driver
(recommended)”.
NOTE: This is the software development environment for the Propeller Chip. Even if you are not
planning to develop Coyote-1 software at this time, you need to perform this step because the
installer loads the USB to Serial chip driver necessary for OpenStomp™ Workbench to
communicate with the Coyote-1.
3. Run “OpenStomp™ Workbench Setup.msi” (located in C:\ OpenStomp(TM) Workbench\”).
4. If you do not already have the appropriate .NET framework installed, you will be directed to
Microsoft’s website where you can download and install it. You can install a higher rev .NET
framework than required if desired.
NOTE: A copy of the .NET 2.0 Compact framework is in C:\OpenStomp(TM) Workbench\.NET
Framework 2.0, but I have not yet been able to test it on a machine that did not already have the
framework installed.
5. Complete the OpenStomp™ Workbench installation.
12
Chapter 6
Overview
The Coyote-1 is a digital guitar effects pedal based on the Propeller processor from Parallax. The
Propeller is a unique embedded microprocessor containing 8 independent “cogs”. Each cog is
essentially a dedicated microprocessor. All 8 cogs execute simultaneously.
The Coyote-1 was designed to be Open-Source. A big part of that challenge was creating an
infrastructure through which developers could create effects modules that could interoperate, be
configured by non-technical end users, and be freely exchanged. To accomplish this, the Coyote-1 uses
the concept of effect modules. An effect module is a piece of software which implements one (or
possibly more than one) effect and which executes on one of the Propeller processor’s 8 cogs.
Effect modules are interconnected by virtual signal pathways called conduits, which connect to sockets
on those effect modules. Sockets are virtual data exchange ports through which a single 32 bit value is
exchanged every audio sample period (i.e. at a rate of 44 KHz, which is approximately once every 22.7
microseconds). There are two different types of conduits: signal conduits which carry audio data and
control conduits which carry control data (such as the output of the buttons and knobs).
The pedal contains a number of system resources which implement sockets on which they output or
input data (the audio jacks, the buttons, the knobs, the LEDs, etc.). To turn an effect module into
something you can actually use, you must specify the conduit routing between the various system
resources and the effect module. This is accomplished using the OpenStomp™ Workbench application.
A specific configuration of effect moules, system resources, and the conduit routing which
interconnects them is called a patch. OpenStomp™ Workbench provides a graphical interface in which
patches can be authored, loaded, saved, and transferred to/from the Coyote-1.
OpenStomp™ Workbench also allows users to load/save and transfer effects modules to/from the
Coyote-1.
Once the Coyote-1 has been loaded with a collection of patches and effects modules, those patches can
be accessed using the foot switches without connecting the Coyote-1 to a computer.
The Coyote-1 ships with a factory installed collection of patches and effect modules. If at any time you
wish to restore the factory configuration, instructions for doing so can be found in Chapter 8.
Chapter 6 Overview
The Coyote-1 can hold up to 15 patches, and up to 16 effect modules in its EEPROM memory, and an
additional 4 effect modules can be compiled into the O/S at any given time.
13
Chapter 7
Using the Pedal
Connecting Equipment
Connect the Coyote-1 to your equipment as shown below. The video output is not necessary unless you
are running video applications (the standard O/S build, and standard effects, do not use it). The PC
connection via USB is only necessary when configuring the pedal or loading software; the pedal can
operate without a PC connection.
The functional assignment of the three ¼ inch jacks is patch dependant. The standard assignment for
monaural single input / single output patches is to use “IN-L” as the input, and “OUT-L” as the output.
Chapter 7 Using the Pedal
Note: The IN-L jack is a very high-impedance input (~1M Ohm), suitable for high impedance devices such
as electric guitars. The IN-R input (because of its dual function as OUT-R) is a medium impedance input.
Plugging a high impedance device (like an electric guitar) into IN-R will result in a rolling off of the high
frequencies. If you need to plug a high impedance device into IN-R, try running it through another guitar
stomp box first. The other stomp box will act a pre-amp to convert the signal to low impedance. Guitars
which contain built-in preamps will work well with IN-R.
14
Boot
When you first apply power to the pedal it will display the Coyote-1 O/S revision.
Coyote-1 O/S
v1.0.0
After booting the Coyote-1 O/S will load “Patch 0” and start it running. In the default shipping
configuration Patch 0 will be the Tremolo patch.
Patch: 0
Tremolo
Controlling a Patch: Knobs
To modify patch parameters, spin the knobs. The functional assignment of the knobs is patch
dependant. When you rotate a knob the pedal will display the knob being changed (“K0” in the image
below, for “Knob 0”), the parameter assigned to that knob (“Delay” below), the current value (835
below), and the units (mSec below, or “milliseconds” (1000 milliseconds = 1 second).
The O/S implements “sticky” knobs, which means that if you rotate a knob the knob will not begin to
modify the assigned parameter’s value until you have rotated its position to match the current
parameter value. If you start spinning a knob and the parameter does not change, just keep spinning
the knob across its full range; when you match the current value the knob will become “unstuck”, and
the display value will begin to follow the knob position.
K0:Delay
835 mSec
S
Some patches may not make use of all 4 knobs. If a knob has not been assigned to a function then the
parameter name will be displayed as “<Unassigned>”, and rotating the knob will have no effect on the
patch being heard.
K2: Unassigned
92%
Controlling a Patch: Buttons
The function of the two “foot switch” buttons is patch dependant. Typically the buttons are used to
turn different effects on and off, and typically the on/off state is represented by the LED associated with
each button.
Chapter 7 Using the Pedal
By convention the right most knob (K3) is typically used to control the final gain stage (output volume)
of a patch.
15
Switching Patches
To switch between patches, step on both button simultaneously. An arrow will appear pointing to the
current patch number.
Patch: 0
Tremolo
Clicking the right button will advance to the next patch. Clicking the left button will go backwards one
patch. Stepping on both buttons simultaneously will load (and start) the currently selected patch.
NOTE: If the selected patch is the same as the patch which was running when patch select mode was
entered, the patch will NOT be reloaded, but will continue to run undisturbed.
Reformatting the EEPROM
Performing a EEPROM format will erase all patches and modules stored in EEPROM. Once reformatted,
patches and modules can be reloaded into EEPROM using the OpenStomp™ Workbench application.
NOTE: It is recommended that the patches and modules you develop be archived on your PC, and that
you do not rely on the pedal’s EEPROM as your only patch/module storage.
Why reformat? If you create a custom module or patch which crashes the pedal when it attempts to
load Patch 0 on boot then reformatting can be used to get the O/S booting again so that it will talk to
the Workbench application.
To reformat the EEPROM, hold the left button down while powering up the device, then click the right
button when prompted. Clicking the left button will cancel the reformat and boot normally.
Reformat EEPROM?
Left:No
Right:Yes
Patch / Module Load Errors
Chapter 7 Using the Pedal
If a patch fails to load successfully due to a patch or module error then a numeric error code will be
briefly displayed. A list of error codes can be found in Chapter 13.
16
Error: 1
The Error codes are defined in the source file COYOTE1_HW_Definitions.spin.
Real Time Error: Output Clipping
If the final digital output value (i.e. the value sent to the DAC) reaches its maximum then a small upward
pointing triangle will appear in the upper right corner of the display. This is an indication that the output
is potentially becoming distorted by going outside of the available output range (i.e. clipping).
Patch: 0
Tremolo
Output clipping may be caused by too high an input signal, or too much gain in the effects chain
composing the current patch.
NOTE: Clipping is only detected at the final output stage. It is possible to have audible clipping distortion
occur within a patch and not trigger the “Output Clipping” indicator if the clipping occurs in one effect
module and some subsequent effect module reduces the gain.
Real Time Error: Time Overflow
The Coyote-1 operates at a standard sampling frequency of 44kHz. That means that each effect module
typically has one 44kHz sample window (22.7 microseconds) in which to process a given sample. The
OpenStomp™ architecture refers to this interval as a “microframe”.
Effect modules can self-report to the O/S if they take more than their allotted 22.7 microseconds, and
the O/S will display a Time Overflow indication in the upper right hand corner of the display.
Patch: 0
Tremolo
NOTE: All standard Open Stomp modules implement Time Overflow reporting.
Chapter 7 Using the Pedal
NOTE: It is possible to write a module which operates at a lower sample rate by taking more than one
microframe to process a sample. Such a module can still implement Time Overflow reporting by selfreporting when it goes over its self-allotted processing interval.
17
Chapter 8
Restoring the Factory Configuration
There are two different ways to crash the Coyote-1:
One is to install a bad O/S build, or somehow corrupt the build you have. That situation can be
recovered by just recompiling a good O/S build from the CD and using the Propeller Tool to load it onto
the Coyote-1.
The second way to crash is to corrupt the EEPROM data with bad patches, or bad dynamic modules, or
bad configuration data. That situation can be remedied by erasing the EEPROM per the “Reformatting
the EEPROM” section of Chapter 7, but when you’re done you’ll have an empty EEPROM and you’ll need
to reload any patches or modules you were using.
Chapter 8 Restoring the Factory Configuration
If you don’t want to go through the motions of restoring your configuration piecewise, you can use a
tool called “HAM” (the “Hydra Asset Manager”) to reload the entire EEPROM (OS, modules, and
patches) to the factory configuration. HAM was written by Richard Benson to manage EEPROM data for
Andre’ LaMothe’s “Hydra” Propeller-based video game system
(http://www.xgamestation.com/view_product.php?id=33 ). Because the Coyote-1 uses the same pins
for video as the Hydra, HAM will also work on the Coyote-1.
18
To restore the factory configuration using HAM:
1. Connect the Coyote-1 to your PC using the mini-USB cable and power it on.
2. Start HAM (It should be locate in your “C:\Coyote-1\Additional Utilities\Hydra Asset
Manager (HAM)\” directory).
3. Select the COM port on which the Coyote-1 is attached.
4. It is helpful, but not necessary, to connect a video monitor to the Coyote-1 so you can watch
the progress of HAM.
5. Click “Load HAM Driver”. You will see the button change states when the load is complete.
If you have video attached, you will see the HAM driver screen appear on the attached
display.
6. Drag the factory configuration .eeprom file into the black “Memory Map” box in the HAM
window. The configuration file shoud be located in your “C:\Coyote-1\Coyote-1 Firmware\”
directory, and will be named something like “Coyote-1 Factory Configuration Image 001 (OS
1.0.2).eeprom”.
7. Click “Upload to Hydra”. When the upload completes a dialog box will appear.
8. Cycle power on the Coyote-1, and it will boot into the restored configuration.
Richard Benson maintains HAM here:
http://forums.parallax.com/forums/default.aspx?f=33&p=1&m=168490
Chapter 8 Restoring the Factory Configuration
NOTE: It’s also possible to use the “Download from Hydra” button in HAM to take a “snapshot” of your
Coyote-1’s EEPROM, which you could then reload at a later time using the method above.
19
Chapter 9
Using OpenStompTM Workbench
Connecting to the Coyote-1
Before starting OpenStomp™ Workbench, attach the Coyote-1 to your PC using the supplied mini-USB
cable. Windows will assign the Coyote-1 a dedicated virtual COM port.
Chapter 9 Using OpenStompTM Workbench
When you first start OpenStomp™ Workbench you will see the set of available System Resources (green)
in the Patch Editor pane. Both the “Modules” list and the “Patches” list will be blank.
20
Using the “COM Port:” drop down menu in the upper right corner, select the COM port on which the
Coyote-1 is attached and then click “Connect”. The “Modules” list and the “Patches” list will be updated
to reflect the Effect Modules and Patches currently present on the attached device.
Note:
The Coyote-1’s COM port may not appear in the “COM Port:” drop down menu if you
attached it after starting Workbench, or switched USB ports. To update the COM port list
select “Refresh COM Port List” from the “Communications” drop down menu.
Advanced:
OpenStomp™ Workbench closes the COM port when not communicating with the Coyote-1
even though the state appears to be “Connected”. This is done so that new O/S code can
be compiled in the Propeller IDE and loaded into the device without quitting Workbench or
disconnecting.
Advanced:
If you added, changed, or removed Static Modules by compiling and loading a new O/S
build, you can update the “Modules” list by clicking “Diconnect”, and then clicking
“Connect”.
System Resources
Knobs
There are 4 knob resources, representing the 4 physical knobs on the Coyote-1. Knob 0 is the left-most
knob. The Init conduit allows you to specify the initialization value of the knob when creating a patch (0100%). The output conduit outputs the knob’s position.
LEDs
There are 2 LED resources, representing the 2 physical LEDs. LED 0 is the left-most LED.
Chapter 9 Using OpenStompTM Workbench
Buttons
There are 2 button resources, representing the 2 physical button on the Coyote-1. Button 0 is the leftmost button. The Init conduit allows you to specify the initialization state of the button’s “+Toggle”
output. The “+Toggle” output toggles its value each time the button is pressed and released. The
“+Momentary” output reflects button’s current state (down or up).
21
Audio
There are 4 audio resources, representing the 4 audio ports. “Audio In (Right)” and “Audio Out (Right)”
share the same physical jack.
Gain
There is a gain resource which is typically used as a final output volume control for a patch, and is
typically configured to be controlled by Knob 3. The “In” and “Out” conduits are the input and output
audio conduits respectively. The “Gain” conduit (have you guessed already?) sets the gain.
Loading a Patch
You can load a patch into the Editor by either selecting “Open Patch” from the “File” menu, or by right
clicking on a Path in the “Patches” list and selecting “Load this Patch into the Editor”.
Note: The Editor cannot show an Effect Module in the Editor Pane if that Effect Module does not exist
in the connected Coyote-1 device. If you attempt to load a Patch which contains an Effect
Module that is not currently present in the Coyote-1 (either as a Static Module or as a Dynamic
Module), then an error will be displayed, and the Patch will load without the missing Effect.
Working in the Editor
Chapter 9 Using OpenStompTM Workbench
The large black grid area is the Patch Editor Pane. Patches are created by interconnecting System
Resources and Effects Modules inside the Editor Pane.
22
Zoom and Pan
Rotating the mouse wheel will zoom in and out (the mouse cursor must be over the Editor Pane). Zoom
can also be performed by clicking the “+” or “-“ buttons at the bottom right of the Editor Pane.
Clicking “Home” will return the Editor Pane to 1:1 zoom and will pan to the home position (the upper
left of the work area).
Holding down both the left and the right mouse buttons simultaneously while moving the mouse will
pan the editor pane.
Moving Objects
To move an Object (i.e. a System Resource (green) or an Effect (purple)) click the top “Title Bar” region
of the object and drag it. Objects cannot be overlapped. If you attempt to overlap objects a red
boundary will appear, and if you release the mouse button while in an overlapping position the object
will return to its original location.
Adding Effects to a Patch
To add an Effect Module to a Patch, right-click an Effect Module in the “Modules” list and select “Add to
Editor Patch”. Static Modules (shown in red in the “Modules” list) and Dynamic Modules (shown in
purple in the “Modules” list) can both be added to Patches.
The added Module will appear in the upper left corner of the working area (you may need to zoom/pan
to see it), and may overlap existing objects. Play nice and drag it somewhere better before hooking it
up.
Connecting Objects
Objects (System Resources and Effects) have connection points called sockets which can be connected
to one another using wires called conduits.
2.
Click the left mouse button. A blue line will appear and will follow the mouse.
3.
Hover the mouse over the left hand edge of an input socket (i.e. one on the left hand
side of an object). The input socket type (Signal (blue) or Control (brown)) must
match the output socket type. A yellow circle will appear when hovering over a valid
input socket.
4.
Click the left mouse button. A conduit will be created between the two sockets.
To delete a conduit:
1.
Hover the mouse over either the right hand edge of the output socket from which the
conduit originates, or over the left hand edge of the input socket to which the conduit
terminates. Click the right mouse button. A popup menu will appear. Select “Remove
Conduit”.
Chapter 9 Using OpenStompTM Workbench
To create a conduit:
1.
Hover your mouse over the right hand edge of an output socket (i.e. one on the right
hand side of an object). A yellow circle will appear at the edge of the conduit.
23
Modifying Static Assignments
Any unconnected input socket (i.e. a socket to which a conduit has not been attached) has a default
static assignment value which is shown in a light yellow bubble to the left of the socket. To modify the
static assignment, hover the mouse over the left edge of the conduit and click the right mouse button.
A popup menu will appear. Select “Change Static Assignment” from the popup menu. A dialog box will
appear allowing you to modify the assigned value.
Main Menu Commands
Chapter 9 Using OpenStompTM Workbench
File
24
New Patch
Creates a “Blank Slate” in the Patch Editor Pane, containing only the built in System Resources.
Open Patch
Opens a Patch file (.c1p) from disk into the Patch Editor Pane.
Save Patch
Saves the current patch (in the Patch Editor Pane) to a Patch file (.c1p) on disk.
Patch
Run
Loads the current patch onto the Coyote-1 and starts it executing. The patch number on the
device will display as “--" to indicate that the patch is a “temporary” load and is not stored in
one of the regular numbered patch slots.
Unroute All Conduits
Removes all conduits from the current patch in the Patch Editor Pane.
Coyote-1
Connect
Attempts to establish a connection with the Coyote-1 device on the currently selected COM
port. Selecting this option is equivalent to clicking the “Connect” button in the main window.
Reset
Performs a hardware reset on the attached Coyote-1 device.
Format EEPROM
Erases the Effects Modules and Patchs from the Coyote-1 EEPROM. Does not erase the
Coyote-1 O/S, which is also stored in EEPROM.
Erase All Dynamic Modules
Erases the Dynamic Modules stored in EEPROM, but does not erase the Patches.
Erase All Patches
Erases the Patches stored in EEPROM, but does not erase the Dynamic Modules.
Communications
Refresh COM Port List
Updates the “COM Port:” drop down list to show all currently existing COM ports. You may
need to select this option if the Coyote-1 was attached after starting Workbench, or was moved
to a new USB port.
Help
About
Shows software revision, revision history, and copyright info.
Load From File
Loads a dynamic module from a Coyote-1 module file (.c1m), and stores it in the Coyote-1’s
EEPROM at the selected position. This operation can not be performed on the first four
positions, which are reserved for static modules.
Save to File
Saves the selected module to a file as a dynamic module. This operation can be performed on
both static modules and dynamic modules.
Erase
Erases the selected modules. This operation can only be performed on dynamic modules.
Add to Editor Patch
Adds the selected module to the patch editor pane.
Copy From Copies the static module selected from the hierarchical sub-menu to the currently selected
dynamic module position.
Patch List Menu Commands
Load From File
Loads a patch from a Coyote-1 patch file (.c1p) into the selected patch location in Coyote-1
EEPROM.
Save to File
Saves the selected patch to a Coyote-1 patch file (.c1p).
Chapter 9 Using OpenStompTM Workbench
Module List Menu Commands
25
Erase
Erases the selected patch from the Coyote-1 EEPROM.
Store the Current Editor Patch Here
Copies the current patch from the patch editor pane to the selected patch location in Coyote-1
EEPROM.
Load This Patch Into the Editor
Copies the selected patch from Coyote-1 EEPROM to the patch editor pane.
Conduit Routing Restrictions
The following restrictions apply to conduit routing:
Chapter 9 Using OpenStompTM Workbench
1.
2.
3.
4.
5.
6.
26
Output Sockets can only be connected to Input Sockets.
Multiple Output Sockets cannot be connected to a single Input Socket.
A single Output Socket can be connected to multiple Input Sockets.
Signal Sockets (blue) can only be connected to other Signal Sockets.
Data Sockets (brown) can only be connected to other Data Sockets.
Initialization Sockets (purple) can only be assigned a static value (they cannot be connected to
other Sockets).
Chapter 10
Under the Hood
Block Diagram
¼ Inch
Output
Jack
¼ Inch
Input
Jack
¼ Inch
Output
Jack
CODEC
Headphone
Amplifier
Headphone
Jack
Video Out
I2S Serial
Knob 1
Knob 2
Knob
Conditioning
Circuit
Propeller
Processor
Button 0
8 Bit Data Bus
Knob 3
512K Byte
SRAM 1
PLD
19 Bit Address Bus
512K Byte
SRAM 0
Knob 0
LED 0
LED 1
Button 1
DC Power
Jack
5V & 3.3V
Linear
Regulators
128K EEPROM 0
(Code & Data)
I2C Serial
USB
Jack
USB
To Serial
Converter
16x2
LCD
128K EEPROM 1
(User Defined)
Expansion
Port
Chapter 10 Under the Hood
Note: The shipping configuration of the Coyote-1 actually contains 3 512K SRAMs. The block diagram
has not yet been updated to reflect this.
27
Chapter 10 Under the Hood
Software Architecture
28
Propeller Pin Assignments
Pin
P0
P1
P2
P3
P4
P5
P6
P7
Primary Function
MEMBUS_CNTL_0
MEMBUS_CNTL_1
MEMBUS_CNTL_2
KNOB_STROBE
KNOB_SHUNT
BUTTON_READ
MEMBUS_CLK
KNOB_0
P8
P9
P10
P11
P12
P13
P14
P15
KNOB_1
KNOB_2
KNOB_3
CODEC_BCK
CODEC_SYSCLK
CODEC_DATAO
CODEC_DATAI
CODEC_WS
P16
P17
P18
P19
P20
P21
P22
P23
MEMBUS_D0
MEMBUS_D1
MEMBUS_D2
MEMBUS_D3
MEMBUS_D4
MEMBUS_D5
MEMBUS_D6
MEMBUS_D7
P24
P25
P26
P27
P28
P29
P30
P31
VIDEO_0
VIDEO_1
VIDEO_2
LCD_MUX
EEPROM_SCK
EEPROM_SDA
USB_RXD
USB_TXD
Alternate Function
LCD_REGSEL
LCD_READ
LCD_ENABLE
BUTTON_MUX
MEMBUS_CNTL[2..0]
0x0
0x1
0x2
0x3
0x4
0x5
0x6
Function
Write SRAM Byte
Read SRAM Byte
Write SRAM Addr LOW [SRAM_A07..SRAMA00]
Write SRAM Addr MID [SRAM_A15..SRAMA08]
Write SRAM Addr HIGH [SRAM_A20..SRAMA16]
Set CCR (CODEC Control Register)
Set GPIO0 (General Purpose I/O 0)
PLD Register: CCR (CODEC Control Register)
Chapter 10 Under the Hood
MEMBUS Interface
29
Bit
7
6
5
4
3
2
1
0
Function
(Reserved)
CODEC_MC2
CODEC_MC1
CODEC_MP5
CODEC_MP4
CODEC_MP3
CODEC_MP2
CODEC_MP1
Note: The CODEC_yyy bits each control the corresponding CODEC_yyy pin directly. For an
understanding of the various MCx and MPx pin functions, refer to the NXP UDA1345 CODEC
data sheet.
PLD Register: GPIO0 (General Purpose I/O 0)
Bit
7
6
5
4
3
2
1
0
Function
(Reserved)
(Reserved)
(Reserved)
(Reserved)
(Reserved)
LED1
LED0
LCD_BACKLIGHT
Chapter 10 Under the Hood
Note: The LCD_BACKLIGHT is configured in hardware to be on whenever power is applied. Toggling
LCD_BACKLIGHT will have no effect.
30
Chapter 11
Creating Custom Effects Modules
This is the true joy of living. This being used for a
purpose recognized by yourself as a mighty one.
This being thoroughly used up before being
thrown on the scrap heap. This being a force of
nature instead of a feverish, selfish little clod, full
of ailments and grievances, complaining that the
world will not devote itself to making you happy.
- G.B. Shaw
The job of creating a custom effect is basically one of defining the effect’s inputs/outputs (called
sockets), and then writing the software to read the input sockets and create the proper behavior on the
output sockets.
The Coyote-1 uses a 44kHz audio sample rate, which means that every 1/44000th of a second
(approximately every 22.7 microseconds) the ADC (analog to digital converter) hardware captures a
digital sample from each of the two analog input channels (In-L (left) and In-R (right)), and outputs a
digital sample on each of the two analog output channels (Out-L (left) and Out-R (right). In general, an
audio effect module must keep up with this sample rate, which means that it has 22.7 microseconds to
read its input sockets and write new values to its output sockets. The exception to this rule is effect
modules which are specifically written to operate at a lower sample rate. A 22kHz effect module would
Chapter 11 Creating Custom Effects Modules
If you have not already familiarized yourself with the Propeller chip’s hardware and software
architecture, and with the Propeller IDE (the “Propeller Tool” software), you should take a look through
the “Propeller Manaul” PDF and do so. The Propeller Manual is installed when you install the Propeller
Tool, and can be accessed quickly from the “Help” menu within the Propeller Tool.
Before you learn to write custom effects, take a quick look at the existing effects modules to
familiarize yourself with their structure. The effect module source files all have the form
“COYOTE1_MODULE_module_name.spin”.
This chapter will use the Tremolo effect (COYOTE1_MODULE_Tremolo.spin) as an example. Inside
OpenStomp™ Workbench, the Tremolo effect looks like this:
31
read its input sockets only once every 1/22000th of a second, and write its output sockets once every
1/22000th of a second.
In the Coyote-1 system architecture, the native 44kHz sample period is referred to as a microframe.
The Coyote-1 O/S provides a mechanism by which effect modules synchronize to the start of a
microframe, and by which they can report an overrun error if they ever take more than a single
microframe to process their data.
Socket Types
There are three types of sockets; signal sockets, control sockets, and initialization sockets. Signal
sockets carry audio data, and are colored blue in the Workbench editor. Their data is signed, and they
have a maximum range of 0xffffffff (-2147483647) to 0x7fffffff (2147483647).
Control sockets carry control information (data values which affect the behavior of effect modules
or system resources), and are colored brown in the Workbench editor. Their data is unsigned, and they
have a maximum range of 0x00000000 (zero) to 0x7fffffff (2147483647). Sometimes a control socket is
designed to implement a two state (on/off) function. In these cases the convention is to name the
socket with “+” prefix. Two state inputs treat all input values below 0x40000000 as “false”, and all input
values above 0x40000000 as “true”. Two state outputs are set to 0x00000000 when “false”, and
0x7fffffff when true.
Initialization sockets are a special form of input control socket which reads its input value only once
(during the startup of a patch). They are colored light purple. Their data is unsigned, and they have a
maximum range of 0x00000000 (zero) to 0x7fffffff (2147483647).
The Module Descriptor
Chapter 11 Creating Custom Effects Modules
The module descriptor is a data structure which describes the attributes of an effect module,
including its name, its size, its signature, its revision, how many conduits it has, the conduit definitions,
how much SRAM it requires, and how much RAM it requires.
Early on in the effect module code you’ll see the get_module_descriptor_p function, which allows
the Coyote-1 O/S to get a pointer to the effect modules’ module descriptor:
32
PUB get_module_descriptor_p
' Store the main RAM address of the module's code into the module descriptor.
long[ @_module_descriptor + hw#MDES_OFFSET__CODE_P] := @_module_entry
' Return a pointer to the module descriptor
return (@_module_descriptor)
Next, you’ll see the module descriptor definition:
DAT
'-----------------------------------'Module Descriptor
'-----------------------------------_module_descriptor
long
hw#MDES_FORMAT_1
long
(@_module_descriptor_end - @_module_descriptor)
long
(@_module_end - @_module_entry)
long
0
long
long
long
long
long
long
long
long
$03_80_00_00
$00_01_00_00
0
0
0
0
0
0
'Module descriptor format
'Module descriptor size (in bytes)
'Module legth
'Module code pointer (this is a placeholder which gets overwritten during
'
the get_module_descriptor_p() call)
'Module Signature
'Module revision (xx_AA_BB_CC = a.b.c)
'Microframe requirement
'SRAM requirement (heap)
'RAM requirement (internal propeller RAM)
'(RESERVED0) - set to zero to ensure compatability with future OS versions
'(RESERVED1) - set to zero to ensure compatability with future OS versions
'(RESERVED2) - set to zero to ensure compatability with future OS versions
_module_descriptor_end
byte
long
long
0
6
'(RESERVED3) - set to zero to ensure compatability with future OS versions
'Number of sockets
'Socket
byte
long
byte
long
long
long
0
"In",0
0 | hw#SOCKET_FLAG__SIGNAL | hw#SOCKET_FLAG__INPUT
0 {null string}
0
0
0
'Name
'Flags and ID
'Units
'Range Low
'Range High
'Default Value
'Socket
byte
long
byte
long
long
long
1
"Out",0
1 | hw#SOCKET_FLAG__SIGNAL
0 {null string}
0
0
0
'Name
'Flags and ID
'Units
'Range Low
'Range High
'Default Value
'Socket
byte
long
byte
long
long
long
2
"Rate",0
2 | hw#SOCKET_FLAG__INPUT
"mSec",0
LFO_PERIOD_MIN_MSEC
LFO_PERIOD_MAX_MSEC
500
'Name
'Flags and ID
'Units
'Range Low
'Range High
'Default Value
'Socket
byte
long
byte
long
long
long
3
"Depth",0
3 | hw#SOCKET_FLAG__INPUT
"%",0
0
100
100
'Name
'Flags and ID
'Units
'Range Low
'Range High
'Default Value
'Socket
byte
long
byte
long
long
long
4
"+Bypass",0
5 | hw#SOCKET_FLAG__INPUT
0 {null string}
0
1
0
'Name
'Flags and ID
'Units
'Range Low
'Range High
'Default Value
'Socket
byte
long
byte
long
long
long
5
"+On",0
6
0 {null string}
0
1
1
'Name
'Flags and ID
'Units
'Range Low
'Range High
'Default Value
byte
long
"Tremolo",0
hw#NO_SEGMENTATION
'Module name
'Segmentation
0
A full definition of the module descriptor format can be found in Chapter 15.
Great care should be taken when creating a module descriptor. The module descriptor must be
formatted exactly to the module descriptor format definition in Chapter 15 or the O/S will not be able to
interpret it properly.
You will see in the module descriptor format that a socket range can be specified for each socket.
The range is used only for the purposes of displaying values to the user when they rotate a knob
connected to that socket by a conduit. For example, a knob always outputs values from 0x00000000 to
0x7fffffff. If you specify a range_low of 0 and a range_high of 100, and connect a knob to that conduit
using Workbench, and rotate the knob fully clockwise, the user will see the value “100” displayed, and
the value arriving at the socket will be 0x7fffffff.
This “universal” ranging of control socket values (i.e. that control socket values always operate
across the full range 0x00000000 to 0x7fffffff) was done to ensure the maximum flexibility when
interconnecting objects in Workbench.
The Module Code
The module code will always consist of 6 basic regions:
1)
2)
3)
4)
5)
6)
Pointer Loading
Initialization
The Synchronization Loop
The Bypass Block
Effect Processing
Data Declaration
Chapter 11 Creating Custom Effects Modules
A Word about Socket Ranges
33
Pointer Loading
In this section the data pointer to the various system objects (frame counter, module control block,
etc) are loaded, and the pointers to all the socket locations are set up. This section will typically
have the same form for all modules, though the socket pointers, their names, and their quantity will
be unique.
Chapter 11 Creating Custom Effects Modules
Initialization
In this section any necessary data initialization is performed. This section will be different for all
modules, and will be very application specific. In the case of the tremolo module, there is a single
variable to initialize.
34
The Synchronization Loop
This code should be identical for all modules. The synchronization loop waits for the start of a
microframe boundary (i.e. the start of an audio sample interval) before dropping into the execution
of the effect code. It also detects overrun conditions (i.e. whether the effect code took longer than
its allotted sample interval to execute) and reports them to the O/S if they occur.
The Bypass Block
Most effects modules will choose to implement “Bypass” functionality, which gives the user the
ability to step on one of the foot switches to turn the effect on or off.
Effect Processing
This is where the real work gets done. The code will read the input sockets, work its magic, write
the output sockets, and end with a jump back to the synchronization loop to wait for the next
sample.
Data Declaration
This is where the variables and data are declared.
To create a custom effect module you would:
1) Author the effect module as a Propeller code module (the existing
COYOTE1_MODULE_Tremolo.spin is an example of an effect module).
2) Link the effect module into the O/S build by modifying the COYOTE1_static_module_list.spin
module to include the new module.
3) Recompile the O/S, creating a version which includes the new module as a static module (i.e as
a compiled-in module).
4) Load the O/S onto the device.
5) Create a patch which uses the new module.
6) Run the patch to test the new module.
7) Iteratively test, modify, recompile, load until the effect module is complete and functional.
8) Use OpenStomp™ Workbench to save the module as a dynamic module. Once saved as a
dynamic module the new module can be easily distributed to other Coyote-1 users.
Chapter 11 Creating Custom Effects Modules
The Effects Module Creation Process
35
Linking an Effect Module as a Static Module
Linking an effect as a “Static Module” means that it will be compiled into the O/S build. To link an effect
module as a static module:
Chapter 11 Creating Custom Effects Modules
1. Load the file COYOTE1_static_module_list.spin into the Propeller Tool.
2. List the new module in the OBJ section as shown below. The name in quotes must match the
filename of the effect module (excluding the .spin extension).
3. Replace any of the 4 static modules in the case statement with a call to the new module’s
get_module_descriptor_p function.
4. Save the modified COYOTE1_static_module_list.spin file.
36
Recompiling and Loading the O/S
To recompile the O/S, open the COYOTE1_OS.spin file in the Propeller tool, select it as the currently
displayed file (if it is not already) by clicking its tab, and press:
F11 (to build the O/S and load it into EEPROM)
or
F10 (to build the O/S and load it into RAM)
Useful Coyote-1 Control Socket Value to Time Conversions
Bit Shift
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Decimal Max
2147483647
1073741823
536870911
268435455
134217727
67108863
33554431
16777215
8388607
4194303
2097151
1048575
524287
262143
131071
65535
32767
16383
8191
4095
2047
1023
511
255
127
63
31
15
7
3
1
(Unmodified)
Hex Max
0x7FFFFFFF
0x3FFFFFFF
0x1FFFFFFF
0xFFFFFFF
0x7FFFFFF
0x3FFFFFF
0x1FFFFFF
0xFFFFFF
0x7FFFFF
0x3FFFFF
0x1FFFFF
0xFFFFF
0x7FFFF
0x3FFFF
0x1FFFF
0x0FFFF
0x07FFF
0x03FFF
0x01FFF
0x0FFF
0x07FF
0x03FF
0x01FF
0x0FF
0x07F
0x03F
0x01F
0x0F
0x07
0x03
0x01
Delay in Sec
48806.446523
24403.223250
12201.611614
6100.805795
3050.402886
1525.201432
762.600705
381.300341
190.650159
95.325068
47.662523
23.831250
11.915614
5.957795
2.978886
1.489432
0.744705
0.372341
0.186159
0.093068
0.046523
0.023250
0.011614
0.005795
0.002886
0.001432
0.000705
0.000341
0.000159
0.000068
0.000023
Decimal Max
(Times 3)
Hex Max
Delay in Sec
1610612733
805306365
402653181
201326589
100663293
50331645
25165821
12582909
6291453
3145725
1572861
786429
393213
196605
98301
49149
24573
12285
6141
3069
1533
765
381
189
93
45
21
9
3
0x5FFFFFFD
0x2FFFFFFD
0x17FFFFFD
0xBFFFFFD
0x5FFFFFD
0x2FFFFFD
0x17FFFFD
0xBFFFFD
0x5FFFFD
0x2FFFFD
0x17FFFD
0xBFFFD
0x5FFFD
0x2FFFD
0x17FFD
0x0BFFD
0x05FFD
0x02FFD
0x017FD
0x0BFD
0x05FD
0x02FD
0x017D
0x0BD
0x05D
0x02D
0x015
0x09
0x03
36604.834841
18302.417386
9151.208659
4575.604295
2287.802114
1143.901023
571.950477
285.975205
142.987568
71.493750
35.746841
17.873386
8.936659
4.468295
2.234114
1.117023
0.558477
0.279205
0.139568
0.069750
0.034841
0.017386
0.008659
0.004295
0.002114
0.001023
0.000477
0.000205
0.000068
For example, the “Delay” effect module has a delay range of 0 to 1489msec (0 to 1.489 seconds). To
accomplish this, it declares a range of 0 to 1489 in its Module Descriptor block…
And then computes the delay by shifting the delay socket value right 15 bits…..
Chapter 11 Creating Custom Effects Modules
It is often desirable to have a control socket govern a rage of time, such as the delay interval for an echo
effect or the period of a Low Frequency Oscillator (LFO). A quick and efficient way to compute such an
interval is to simply perform a right-bit-shift on the socket value so that the resulting numeric range
translates into some useful time range (when interpreted as a length of time expressed in microframes).
The following table can be used to determine the time range obtained by right shifting an input socket
value by different amounts (and, in the rightmost columns, by multiplying by an additional factor of 3).
37
When a knob is attached (by a conduit) to the delay socket and rotated fully clockwise, the socket value
will be 0x7fffffff (maximum). After right shifting 15 bits, the value will be 0x0000ffff (or 65535 decimal).
When that value is used to control the echo delay time in microframes, the resulting delay is…
65535 * (1/44000) = 1.489 seconds
Chapter 11 Creating Custom Effects Modules
Note that the sample rate is 44kHz, so the sample interval is 1/44000 of a second.
38
Chapter 12
Working with the Expansion Port
Overview
The Coyote-1 has an expansion port designed to interface with external control devices such as
pedal switch boards and analog foot pedals, or more experimental devices like accelerometers or
proximity detectors.
The expansion port is an extension of the I2C interface on the board (on which also sit the 2 local
EEPROM devices). External devices can be easily interfaced using any of a number of different I2C chips
available commercially. NXP makes I2C chips that provide anywhere from 4 to 16 digital I/O lines (like
the PCA9536 and the PCA9539), as well as ADC and DAC chips (like the PCF8591). Many other
manufacturers also make I2C compatible devices that interface to all kinds of interesting things.
The port can source up to 50mA of current at 3.3V, so low power devices can receive their power
directly from the Coyote-1.
Software Paradigm
The paradigm to follow when creating expansion port devices is to write an accompanying effect
module which effectively functions as a device driver for the new hardware. Most effect modules have
both input and output sockets, but an effect module which is the device driver for a piece of expansion
port hardware like an analog foot pedal might only have an output socket (representing the current
pedal position).
Tips
On the remote board
• Protect against power reversal with a diode.
• Use an I2C I/O expander to provide digital ins/outs
• Use an I2C ADC or DAC to provide analog ins/outs
• Provide pads for a transient line termination on SCL, SDA just in case you need them. (I have
tested without termination on the external device side with no problems and decent looking
signals for a 3 ft cable run.)
• Work whatever magic you like on the far side of the I2C devices.
• Design for use with a standard phone cable, and try to keep the cable length around 3 ft or less.
Standard phone cables do not “cross over”, so pin 1 (which is 3.3V power on the Coyote-1)
should connect to pin 1 (also 3.3V power) on the remote device.
• Put two RJ-11 ports on your device, so that multiple devices can be “daisy chained”.
• Be mindful that if you disturb the operation of the SCL and SDA lines too much (say, by adding
too much load or strong termination) you may prevent the Coyote-1 from booting. This is
Chapter 12 Working with the Expansion Port
I am currently working to create an expansion port device reference design for a simple device. In
the meantime, here are some design tips for those interested in tinkering with the expansion port:
39
because the I2C is shared with the internal Coyote-1 EEPROMs, one of which contains the
Coyote-1’s boot code.
Chapter 12 Working with the Expansion Port
On the Coyote-1
• The O/S needs to be updated to lock/unlock the I2C semaphore around the O/S's I2C accesses. I
have not put that in yet, but it is very simple to add. The I2C semaphore is declared in
COYOTE1_HW_Definitions.spin already, just not used yet (LOCK_ID__I2C).
• Write an "Effect Module" which is a device driver for the external device.
• I found essential in my own testing to re-initialize the external I2C device(s) on every pass
through my main loop in the "device driver" code (typically these devices have one or more
control registers which need to be initialized to configure their I/O). Doing so allows the user to
arbitrarily unplug and re-plug the external device without having to restart the Coyote-1 just to
reinitialize the external device's I2C chips properly.
40
Chapter 13
Error Codes
Chapter 13 Error Codes
The following is a list of error codes which may be reported by the Coyote-1 device.
Value Constant Definition
Description
0
ERR__SUCCESS
No error (internal return value, never displayed)
1
ERR__MODULE_NOT_FOUND
The patch contains a module which is not currently
compiled into the code (static) or located in EEPROM
(dynamic).
2
ERR__MAX_ACTIVE_MOD_EXCEEDED
The patch contains more modules than supported.
3
ERR__CONDUIT_ENG_START_FAILED
Could not start the conduit engine.
4
ERR__MODULE_COG_START_FAILED
Could not start a module.
5
ERR__I2C_WRITE_FAIL
Error writing the I2C bus.
6
ERR__I2C_WRITE_TIMEOUT
Timeout writing the I2C bus.
7
ERR__INDEXED_MODULE_DNE
A module was referenced which does not exist.
8
ERR__ILLEGAL_MODULE_INDEX
Module index out of range.
9
ERR__I2C_READ_FAIL
Error reading the I2C bus.
10
ERR__ILLEGAL_PATCH_INDEX
Patch index out of range.
11
ERR__OUT_OF_SRAM
The modules in the patch, taken together, requested
more SRAM than the total available SRAM pool.
12
ERR__OUT_OF_RAM_POOL
The modules in the patch, taken together, requested
more RAM than the total available RAM pool.
41
Chapter 14
Term
DSP
Module
Effect Module
Conduit
Socket
Static Assignment
Static Module
Dynamic Module
Patch
System Resource
SRAM
RAM
Chapter 14 Glossary of Terms
DAC
ADC
Microframe
42
Frame
Glossary of Terms
Definition
Digital Signal Processing (or Digital Signal Processor).
Using a digital computer to represent an analog signal as a sequence of
discrete samples, and performing operations on that signal digitally.
In the Propeller chip lexicon, a “Module” is a single .spin program file
which may contain a mix of assembly code, Spin code, constants, and
data.
An “Effect Module” is a piece of code which occupies a single COG and
implements one or more audio effects. Sometimes “Effects Module” is
referred to as just a “Module”. Effects Modules can be either “Static” or
“Dynamic” (see definitions).
A data path which connects one output Socket to one or more input
Sockets.
A 32 bit portal thorough which data is exchanged between Effect
Modules and System Resources. Any given Socket is either an Input or an
Output, and caries either Signal or Control data.
A value assigned to an input Conduit to which no Conduit is attached.
An Effect Module which has been compiled into the Coyote-1 O/S kernel.
An Effect Module which is stored in EEPROM.
A specific collection of Effect Modules and System Resources with a
specific Conduit routing.
Objects which appear in OpenStomp™ Workbench and which represent
available hardware and software resources within the pedal, such as
buttons, knobs, I/O ports, etc.
Static Radom Access Memory.
In this case, “SRAM” refers to the 1.5Mbytes of memory in external chips
(i.e. outside the Propeller processor).
Random Access Memory
In this case, “RAM” refers to the 32K of memory inside the Propeller
processor.
Digital to Analog Converter
Analog to Digital Converter
One 44kHz audio sample period (1/44000th of a second, or approximately
22.7 microseconds).
Eight microframes. (NOTE: The concept of “Frames” is not currently used,
but exists for future development).
Chapter 15
Module Descriptor format
The module descriptor consists of 3 regions: The module descriptor header, the socket definitions, and
the module descriptor trailer.
Module descriptor header:
Bits
32
Field
module_descriptor_format
32
32
32
32
module_descriptor_size
module_size
module_code_address
module_signature
32
32
32
32
32
32
32
32
32
module_revision
microframe_requirement
sram_requirement
ram_requirement
reserved0
reserved1
reserved2
reserved3
num_sockets
Description
Identifies the module descriptor format (for future expansion). At
present, the only valid format is 0x3130444d (“MD01” in ASCII).
Length of the module descriptor (in byte)
Length of the module code (in bytes)
The address of the module code, in Propeller RAM.
A unique signature used to identify the module.
See Chapter 16 for a description of the module signature format.
The module revision in the form 0xXXAABBCC = Rev AA .BB.CC
(Reserved for future use. Set to 0.)
The amount of SRAM the module requires.
The amount of Propeller RAM the module requires.
(Reserved for future use. Set to 0.)
(Reserved for future use. Set to 0.)
(Reserved for future use. Set to 0.)
(Reserved for future use. Set to 0.)
The number of sockets the module implements.
Socket definitions (one for each socket):
Bits
8xn
32
8xn
Field
socket_name_string
socket_flags
socket_units_string
32
32
32
range_low
range_high
default_value
Description
The socket name. 32 characters max. Zero terminated.
Length of the module descriptor (in byte)
The socket units (e.g. “mSec”, “Hz”, “%”, etc.). 32 characters max.
Zero terminated.
The max range, for purposes of display only.
The min range, for purposes of display only.
The module revision in the form 0xXXAABBCC = Rev AA .BB.CC
Bits
8xn
32
Field
module_name_string
segmentation_flags
Description
The socket name. 32 characters max. Zero terminated.
Reserved for future use. Set to 0.
Chapter 15 Module Descriptor format
Module descriptor trailer:
43
Chapter 16
Module Signature Format
Each effect module must have a unique 32-bit module signature with the form 0xTTFVVVVV where ‘TT’
is the effect type, ‘F’ is a set of 4 signature flag bits, and ‘VVVVV is a unique ID value.
NOTE:
It is important that every effect module’s signature be unique. The Coyote-1 O/S uses the
signature as the sole means of identifying effects modules. If two effects modules have the
same signature, then the incorrect module may be loaded when the O/S loads a patch.
Chapter 16 Module Signature Format
The current effect type definitions are :
44
0x0n
0x01
0x02
0x03
0x04
0x05
0x06
0x07
MODULATION
Chorus
Flagner
Tremolo
Ring Modulator
Vocoder
PA Mic Control
Compressor
0x1n
0x11
0x12
DELAY
Echo / Delay
Reverb
0x2n
0x20
0x21
0x22
EFFECTS
Distortion
Wah
Synth
0x3n
0x30
EQ
Parametric EQ
0x4n
0x40
0x41
0x42
EQ
Tuner
Note Detector
Signal Generator
The current signature flag bits are:
0x8
0x4
0x2
0x1
OpenStomp™ effect (i.e. released by OpenStomp™)
This bit is set for effects written and released by
OpenStomp™. This bit should be a zero for user
authored effects.
Experimental effect.
This bit should be set when authoring effects for
personal experimentation which will not be (or have
not yet been) released to the public.
(Reserved)
(Reserved)
Chapter 16 Module Signature Format
When you release an effect to the public, it should have a signature of the form 0xTT0VVVVV. You can
email support@OpenStomp.com to request a unique ID Value (VVVVV) for your publically released
effects.
45
Chapter 17
Module Control Block format
Chapter 17 Module Control Block format
The module control block (MCB) is the structure by which the O/S interfaces with an effects module. A
pointer to the MCB is passed to an effects module when it boots, and the effects module reads the
various fields of the MCB to determine the location of its allocated memory (if any SRAM or RAM was
requested by the module). The MCB is also the mechanism for the exchange of socket data (inputs and
outputs) routed to and from the effect.
46
Bits
32
32
Field
ss_block_p
heap_base_p
32
ram_base_p
32
32
32
32
32
32
32*n
microframe_base
runtime_flags
reserved0
reserved1
reserved2
reserved3
socket_exchange[]
Description
A pointer to the system status block
A pointer to the SRAM block granted to the module (per the module’s
SRAM request via the sram_requirement field in its module
descriptor).
A pointer to the RAM block granted to the module (per the module’s
RAM request via the ram_requirement field in its module descriptor).
(Reserved for future use.)
(Reserved for future use.)
(Reserved for future use.)
(Reserved for future use.)
(Reserved for future use.)
(Reserved for future use.)
The number of sockets the module implements.
Chapter 18
Epilogue
This was a triumph.
I’m making a note here:
HUGE SUCCESS.
- GLaDOS, Portal
Man oh man oh man. This has been some ride. It feels great to be finished, but in many ways it’s just
starting. I began this project because I wanted to play around with weird ideas in audio. There was so
much work to do to put the infrastructure in place that it’s really only today, this moment of
“completion”, that the real fun can begin.
Here we go…
"Yes you will," enthused Zaphod, "there's a whole
new life stretching out ahead of you."
"Oh, not another one," groaned Marvin.
Chapter 18 Epilogue
- HHGTTH, D. Adams
47
Download PDF