Subversion Repositories svn.mios

Rev

Rev 1 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
44 tk 1
$Id: README.txt 44 2008-01-30 21:39:30Z tk $
2
 
3
Analog Toolbox V1.1                    (C) 2005 Thorsten Klose (tk@midibox.org)
4
===============================================================================
5
 
6
This application allows to output analog values at the AOUT module
7
depending on analog values, MIDI events and internally generated waveforms
8
 
9
It's definitely not a professional tool, but just a toy for having
10
some fun!
11
 
12
Everybody is welcome for sharing additional modules and/or processing
13
algorithms to the MIDIbox community!
14
 
15
===============================================================================
16
 
17
A precompiled binary is already part of this package:
18
   o project.hex (can be loaded into MIOS Studio)
19
   o project.syx (can be loaded into any SysEx upload tool)
20
 
21
Following tools are required to recompile the code:
22
   o SDCC v2.5.0
23
   o gputils
24
   o perl
25
 
26
The details are described under http://www.ucapps.de/mios_c.html
27
 
28
===============================================================================
29
 
30
Required hardware:
31
   o one MBHP_CORE module
32
   o one MBHP_AOUT module
33
 
34
Optional hardware (not supported by default, but provided by MIOS):
35
   o up to 2*AINX4 for up to 64 analog inputs (reduces the sampling frequency!)
36
   o up to 4*DOUTX4 for up to 128 digital outputs
37
   o up to 4*DINX4 for up to 128 digital inputs
38
   o LCD - but note that it affects the realtime performance!
39
   o up to 8 BankSticks to store waveforms or other tables
40
 
41
===============================================================================
42
 
43
Configuration steps:
44
 
45
   o check the "general application settings" in main.h if changes are
46
     required for your hardware setup
47
     By default 8 analog inputs are used in "UnMuxed mode" (direct
48
     connection to CORE:J5 without AINX4 modules)
49
 
50
     Remember: unusued analog pins on the CORE module should be
51
     clamped to ground!
52
 
53
   o check the pin configuration for the AOUT module in aout.h
54
     The default pinning is equal to the pinning used by MIDIbox CV
55
 
56
   o open map.c and adapt the "signal processing" for your needs
57
 
58
   o the application can be rebuilt with the "make.bat" file
59
     (type "make" in a DOS command shell)
60
 
61
===============================================================================
62
 
63
Description about the most important files:
64
 
65
   - mios_wrapper\mios_wrapper.asm and mios_wrapper\mios_tables.inc:
66
     The MIOS wrapper code and MIOS specific configuration tables
67
 
68
   - pic18f452.c: exports PIC18F452 specific SFRs
69
 
70
   - main.c: the main program with all MIOS hooks
71
 
72
   - aout.c: the AOUT module driver (1)
73
 
74
   - midi.c: the MIDI processing module (2)
75
 
76
   - lfo.c: provides two digital LFOs (3)
77
 
78
   - eg.c: provides an envelope generator (4)
79
 
80
   - map.c: handles the "signal processing" (analog output values are
81
     determined here) (5)
82
 
83
There are additional .h files for all .c files which contain
84
general definitions and the declaration of global functions/variables
85
These .h files must be included into the program parts which
86
get use of these globals
87
 
88
 
89
-------------------------------------------------------------------------------
90
(1) aout.c
91
 
92
this module provides following global variables:
93
 
94
   unsigned int aout_value[8]   (12bit value)
95
 
96
   accessible with:
97
      aout_value[0]    for the first AOUT
98
      aout_value[1]    for the second AOUT
99
      ...
100
      aout_value[7]    for the 8th AOUT
101
 
102
 
103
 
104
   aout_gates_t aout_gates    (union with two elements: G0 and G1)
105
 
106
   accessible with:
107
      aout_gates.G0    for the first gate on the AOUT module
108
      aout_gates.G1    for the second gate on the AOUT module
109
 
110
 
111
   value changes will lead to an automatic update on the AOUT module
112
 
113
 
114
-------------------------------------------------------------------------------
115
(2) midi.c
116
 
117
this module provides following global variables:
118
 
119
   midi_note_t midi_note[16]   (union with two elements: NOTE and GATE)
120
 
121
   midi_note[0]   for the first MIDI channel
122
   midi_note[1]   for the second MIDI channel
123
   ...
124
   midi_note[15]  for the 16th MIDI channel
125
 
126
 
127
   Union usage:
128
     midi_note[x].NOTE returns the note number (0-127),
129
     midi_note[x].GATE returns the gate state (0 or 1)
130
 
131
 
132
   unsigned char midi_cc_chn0[128]   for CC values received on MIDI channel #1
133
 
134
   Examples:
135
     midi_cc_chn0[1]   returns the ModWheel Value
136
     midi_cc_chn0[7]   returns the Volume
137
     midi_cc_chn0[10]  returns the Pan position
138
     midi_cc_chn0[11]  returns the expression value
139
 
140
 
141
   unsigned int midi_pitch_bender[16]    for Pitch Bender values
142
 
143
 
144
-------------------------------------------------------------------------------
145
(3) lfo.c
146
 
147
By default two digital LFOs are provided, the selectable rate goes
148
from 0.016 Hz to 97.4 Hz (see lfo_table.inc) - however, above 20 Hz
149
the generated waveform doesn't look so nice anymore on the scope due
150
to quantisation effects (on the other hands: some people drool for
151
such effects ;-)
152
 
153
The LFOs generate a sawtooth waveform, which can be easily transformed
154
into other waveforms by using a waveform table (map.c contains an
155
example, how to convert this saw into a sinewave)
156
 
157
The LFOs are clocked from the USER_Timer() process each 1 mS (see
158
timer configuration in main.c)
159
 
160
Following global variables are available:
161
   unsigned char lfo0_rate,  lfo1_rate    the LFO rate from 0..255
162
   unsigned int  lfo0_value, lfo1_value   the LFO waveform from 0..65535 (16 bit)
163
 
164
-------------------------------------------------------------------------------
165
(4) eg.c
166
 
167
By default one digital ADSR envelope generator is provided, the selectable
168
attack/decay/release rate goes from 1 mS to 2731 mS (see eg_table.inc)
169
 
170
The EGs is clocked from the USER_Timer() process each 1 mS (see
171
timer configuration in main.c)
172
 
173
Following global variables are available:
174
 
175
   eg_state_t    eg0          provides the gate: eg0.GATE = 1 to set, = 0 to clear
176
   unsigned int  eg0_value    the EG value from 0..65535 (16bit)
177
   unsigned char eg0_attack, eg0_decay, eg0_sustain, eg0_release  the ADSR values from 0..255
178
 
179
-------------------------------------------------------------------------------
180
(5) map.c
181
 
182
Thats the central file where incoming and internal values are
183
routed to outgoing values (aout_value[0..7], ...)
184
 
185
Please read the file to get some inspirations
186
 
187
Note that sometimes values need to be converted depending on the
188
resolution. For better readability, some macros have been defined
189
which can be found in aout.h
190
 
191
Example: aout_value[0] is a 12bit value, MIOS_AIN_PinGet(0) delivers
192
a 10-bit value. In order to convert this to a 12bit value, just use
193
the CONV_10BIT_TO_12BIT macro:
194
 
195
   aout_value[0] = CONV_10BIT_TO_12BIT(MIOS_AIN_PinGet(0));
196
 
197
so that the most significant bit of the 10bit value is aligned to the
198
most significant bit of the 12bit value (in fact the value is
199
multiplicated by 4, resp. it is leftshifted 2 times)
200
 
201
 
202
Additional notes to digital inputs and outputs: if DINX4 and/or DOUTX4
203
modules are connected, the number of shift registers have to be
204
defined in main.c, function USER_Init() in the following way:
205
   MIOS_SRIO_NumberSet(4); // for 4 shift registers
206
 
207
Thereafter you can get digital values with:
208
   MIOS_DIN_PinGet(<pin-number>)
209
and set values with:
210
   MIOS_DOUT_PinSet(<pin-number>, <value>)
211
 
212
 
213
Additional notes to module extensions: MIOS provides some hooks which
214
could be useful for some special jobs, e.g. MIDI clock processing.
215
This example demonstrates, how to add a MIDI clock handler:
216
 
217
a) open main.c, search for the MPROC_NotifyReceivedByte function and
218
add following lines:
219
 
220
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
221
void MPROC_NotifyReceivedByte(unsigned char byte) __wparam
222
{
223
   if( byte == 0xf8 ) // MIDI clock has been received
224
     MAP_MIDIClock(); // call MAP_MIDIClock to notify this
225
}
226
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
227
 
228
 
229
b) open map.h, search for "prototypes", and add the function
230
declaration here:
231
 
232
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
233
void MAP_MIDIClock(void);
234
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
235
 
236
 
237
c) open map.c, go to the bottom and add following lines:
238
 
239
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
240
void MAP_MIDIClock(void)
241
{
242
  // do anything here
243
}
244
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
245
 
246
===============================================================================