Subversion Repositories svn.mios

Rev

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

Rev Author Line No. Line
1095 tk 1
HEADER 3 MIDIbox NG User Manual --- First Steps
2
 
3
<P CLASS=INFO><B><A HREF="midibox_ng_manual.html">Back to main page...</A></B></P>
4
 
5
<H1>MIDIbox NG</H1>
6
<H1>User Manual --- First Steps</H1>
7
 
1119 tk 8
<P CLASS=INFO>The aim of this chapter is to give you a rough oversight about the configuration of a <A HREF="midibox_ng.html">MIDIbox NG</A> before your are working through the details of the <A HREF="midibox_ng_manual_ngc.html">.NGC</A>, <A HREF="midibox_ng_manual_ngl.html">.NGL</A> and <A HREF="midibox_ng_manual_ngr.html">.NGR</A> format.</P>
1095 tk 9
 
10
<H2> <IMG SRC="images/bullet.gif" ALT=""> Editing Configuration Files </H2>
11
 
12
<P CLASS=DESC>First of all it makes sense to get familiar with <A HREF="mios_studio.html">MIOS Studio</A> and especially the integrated MIOS Filebrowser, because it will enable you to try out changes in your MIDIbox NG setup quickly by editing the configuration files, and transfering the changes via USB-MIDI.
13
 
14
<P CLASS=DESC>After power-on, your MIDIbox will always load the DEFAULT.NGC and DEFAULT.NGL file - you will see the appr. messages in the MIOS Terminal (click on the image to enlarge):
15
<CENTER><A HREF="mios_studio/mios_studio_mbng1.png"><IMG SRC="mios_studio/mios_studio_mbng1.png" width=401 height=350></A></CENTER>
16
 
17
<P CLASS=DESC>The DEFAULT files will be automatically generated if they don't exist on the connected SD Card.
18
 
19
<P CLASS=DESC>By opening the MIOS Filebrowser tool in MIOS Studio, you will be able to access the files which are stored on SD Card:
20
<CENTER><A HREF="mios_studio/mios_studio_mbng2.png"><IMG SRC="mios_studio/mios_studio_mbng2.png" width=508 height=285></A></CENTER>
21
<P CLASS=DESC>After a click on the "Update" button, files can be uploaded/downloaded from/to your harddisk - but it's especially possible to edit files without the need for an external text editor!
22
 
23
<P CLASS=DESC>After transfering your changes back to the SD Card (press the SAVE button), the new file can be loaded from the MIOS Terminal with the "load" command:
24
<CENTER><A HREF="mios_studio/mios_studio_mbng3.png"><IMG SRC="mios_studio/mios_studio_mbng3.png" width=401 height=350></A></CENTER>
1228 tk 25
<B>UPDATE:</B> since MIDIbox NG V1.019 the file will be loaded automatically whenever it has been uploaded. There is no need to enter the "load" command into the MIOS Terminal after the upload anymore! :-)
1095 tk 26
 
27
<P CLASS=DESC>The filename has to be specified without the .NGC extension.
28
 
29
<P CLASS=DESC>From the MIOS Terminal it's also possible to store the current setup. So - in order to make any setup as your DEFAULT setup which will be restored after power-on, just type:
1113 tk 30
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 31
load &lt;your-setup-file&gt;
32
save default
33
</PRE></TT>
34
-&gt; done! :-)</P>
35
 
36
 
37
<H2> <IMG SRC="images/bullet.gif" ALT=""> Hello World! </H2>
38
 
39
<P CLASS=DESC>Let's start with the obligatory "Hello World" example. Unfortunately this experiment will only work with a LCD which is connected to your core module.
40
 
41
<P CLASS=DESC>In MIOS Filebrowser, create a new configuration file by clicking on the "Create File" button. Name it "hello.ngc", and then click on the "Update" button to re-scan the directory.
42
 
43
<P CLASS=DESC>Click on the "HELLO.NGC" file and push the "Edit Text" button.
44
 
45
<P CLASS=DESC>Thereafter enter following commands into this file:
1113 tk 46
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 47
RESET_HW
48
 
49
LCD "%CHello World!"
50
</PRE></TT>
51
 
1117 tk 52
<P CLASS=DESC>Click on the "Save" button. The AUTOLOAD function should automatically execute the "load hello" command after upload.
1095 tk 53
 
54
<P CLASS=DESC>Your LCD should show the message now!
55
 
56
<P CLASS=DESC><B>Note:</B> detailed informations about the commands which are mentioned at this page can be found in the <A HREF="midibox_ng_manual_ngc.html">.NGC chapter</A>.
57
 
58
<P CLASS=DESC>This is probably also the best place to mention, that filenames (without the .NG* extension) are limited to 8 characters!</P>
59
 
60
 
61
<H2> <IMG SRC="images/bullet.gif" ALT=""> Push me! </H2>
62
 
63
<P CLASS=DESC>The next experiment will work if a DIN shift register (e.g. of a <A HREF="mbhp_din.html">MBHP_DIN</A> or <A HREF="mbhp_dio_matrix.html">MBHP_DIO_MATRIX</A> module is connected to J8/9 of the core module.
64
 
1181 tk 65
<P CLASS=DESC><I><B>New:</B> alternatively you could emulate up to 2 DIN shift registers at port J10A and J10B of a <A HREF="mbhp_core_stm32f4.html">MBHP_CORE_STM32F4</A> module by using the DIO command. In this case, please add the two DIO commands like shown in <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fdiocfg_1.ngc" TARGET="_blank">the diocfg_1.ngc example</A>, and connect the button(s) to J10.D0..D15</I>
66
 
1095 tk 67
<P CLASS=DESC>We want to generate a Note event with a button connected to the D0 pin of the first shift register. The appr. button ID is 1.
68
 
69
<P CLASS=DESC>Add following command to your HELLO.NGC file:
1113 tk 70
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 71
RESET_HW
72
 
73
LCD "%CHello World!"
74
 
75
EVENT_BUTTON id=1  type=NoteOn key=36
76
</PRE></TT>
77
 
1117 tk 78
<P CLASS=DESC>Save the file in the filebrowser - the AUTOLOAD function will automatically execute "load hello" - this step won't be mentioned again in the steps below, because you should have good practice with this procedure now! ;-)
1095 tk 79
 
80
<P CLASS=DESC>Push the button - it should send a Note On event with C-1, velocity 127. When you release the button, it should send C-1 with velocity 0, which equates to NoteOff.
81
 
82
<P CLASS=DESC>These events are displayed in the MIDI IN monitor of MIOS Studio in hexadecimal format (in this case: 90 24 7F when pressed, and 90 24 00 when depressed) and in text format.
83
 
84
 
85
<H2> <IMG SRC="images/bullet.gif" ALT=""> Push me softer! </H2>
86
 
87
<P CLASS=DESC>You want to play a Note with less velocity? Then just change the range of the event:
88
 
1113 tk 89
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 90
EVENT_BUTTON id=1  type=NoteOn key=36 range=0:100
91
</PRE></TT>
92
 
1096 tk 93
<P CLASS=DESC>The MIDI IN monitor of MIOS Studio should now display NoteOn events with velocity 100
1095 tk 94
 
95
 
96
<H2> <IMG SRC="images/bullet.gif" ALT=""> Changing the Channel </H2>
97
 
98
<P CLASS=DESC>Events are sent to MIDI channel 1 by default. If you want to select a different channel, e.g. 3, write:
99
 
1113 tk 100
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 101
EVENT_BUTTON id=1  type=NoteOn key=36 chn=3 range=0:100
102
</PRE></TT>
103
 
104
<P CLASS=DESC>The MIDI protocol provides 16 MIDI channels....
105
 
106
 
107
<H2> <IMG SRC="images/bullet.gif" ALT=""> Changing the Port </H2>
108
 
109
<P CLASS=DESC>...but in some situations it might be helpful to have more!
110
 
111
<P CLASS=DESC>For this purpose, MIDIbox NG provides multiple MIDI ports. With following command:
1113 tk 112
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 113
EVENT_BUTTON id=1  type=NoteOn key=36 chn=3 range=0:100 ports=0100010000000000
114
</PRE></TT>
115
 
116
<P CLASS=DESC>The MIDI event will now be send over USB2 and MIDI OUT2
117
 
118
<P CLASS=DESC><B>Important:</B> the MIDI IN monitor of MIOS Studio won't display this event, because it only allows to select a single input port. Select the second USB port of your MIDIbox NG to display the event, or just run a second MIOS Studio instance, or a different MIDI monitor (such as the <A HREF="http://www.snoize.com/MIDIMonitor/" TARGET="_blank">Snoize MIDI Monitor for MacOS</A> or <A HREF="http://www.midiox.com" TARGET="_blank">MIDI-Ox for Windows</A>).
119
 
120
 
121
<H2> <IMG SRC="images/bullet.gif" ALT=""> Be Verbose! </H2>
122
 
123
<P CLASS=DESC>Now we want to display the button movement on our LCD, because the "Hello World!" message gets boring.
124
 
125
<P CLASS=DESC>Replace the previous EVENT definition by:
1113 tk 126
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 127
EVENT_BUTTON id=1  type=NoteOn key=36  lcd_pos=1:1:1 label="Button #%3i: %3d"
128
</PRE></TT>
129
 
130
Whenever you are pushing the button, the LCD should display: <TT>Button #  1: 127</TT><BR>
131
When it's released the LCD should display: <TT>Button #  1:   0</TT>
132
 
133
 
134
<H2> <IMG SRC="images/bullet.gif" ALT=""> Let there be light! </H2>
135
 
136
<P CLASS=DESC>This experiment requires a DOUT shift register (e.g. of a <A HREF="mbhp_dout.html">MBHP_DOUT</A> or <A HREF="mbhp_dio_matrix.html">MBHP_DIO_MATRIX</A> module connected to J8/9 of the core module) in addition. The anode (long leg) of the LED should be connected at D7 (the first (leftmost) DOUT output pin), the cathode (short leg) to Vs (ground).
137
 
1181 tk 138
<P CLASS=DESC><I><B>New:</B> alternatively you could emulate up to 2 DOUT shift registers at port J10A and J10B of a <A HREF="mbhp_core_stm32f4.html">MBHP_CORE_STM32F4</A> module by using the DIO command. In this case, please add the two DIO commands like shown in <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fdiocfg_2.ngc" TARGET="_blank">the diocfg_2.ngc example</A>, and connect the button(s) to J10A, and the LEDs to J10B</I>
1095 tk 139
 
1181 tk 140
<P CLASS=DESC><B>Beware:</B> the J10 ports and the MBHP_DIO_MATRIX module have no series resistor for the LED! Please use a 220 Ohm resistor between Anode (long leg) and the output pin, otherwise the LED will be fried!
141
 
1095 tk 142
<P CLASS=DESC>So much about the obligatory disclaimer... don't worry, this resistor should be already stuffed on your <A HREF="mbhp_dout.html">MBHP_DOUT</A> module
143
 
144
<P CLASS=DESC>Change the EVENT_BUTTON definition in your HELLO.NGC file as follows:
145
 
1113 tk 146
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 147
EVENT_BUTTON id=1  fwd_id=LED:1  type=NoteOn key=36  lcd_pos=1:1:1 label="Button #%3i: %3d"
148
</PRE></TT>
149
 
150
<P CLASS=DESC>The LED should turn on while you are pressing the button.
151
 
152
 
153
<H2> <IMG SRC="images/bullet.gif" ALT=""> Remote me! </H2>
154
 
155
<P CLASS=DESC>With the previous EVENT_BUTTON statement, play MIDI Note C1 on the virtual MIDI keyboard of MIOS Studio.
156
 
157
<P CLASS=DESC>The LED should be lit whenever you are clicking with the mouse on the lower boundary of the C1 key of the virtual keyboard (velocity has to be >= 64, check this in the MIDI OUT monitor). If you click a bit more higher, the LED won't turn on because the velocity is below the half of the specified range.
158
 
159
<P CLASS=DESC>In other words: the LED will only be lit if the received velocity is greater than int((127-0)/2) = 63. Velocities which are &lt;= this value will turn off the LED.
160
 
161
 
1117 tk 162
<H2> <IMG SRC="images/bullet.gif" ALT=""> Dim me! </H2>
163
 
164
<P CLASS=DESC>While previously the LED was only switched between on and off state depending on the incoming MIDI value, now we want to control the brightness level with the received velocity value instead:
165
 
166
<TT><PRE style="margin-left:50px; font-size:8pt">
167
EVENT_BUTTON id=1  fwd_id=LED:1 dimmed=1  type=NoteOn key=36  lcd_pos=1:1:1 label="Button #%3i: %3d"
168
</PRE></TT>
169
 
170
<P CLASS=DESC>Only the <I>dimmed=1</I> parameter has been added. The LED will change the brightness over the 0..127 value range in 16 levels.
171
 
172
<P CLASS=DESC>Just for fun you could also control the brightness from a CC event:
173
<TT><PRE style="margin-left:50px; font-size:8pt">
174
EVENT_LED  id=1  dimmed=1  type=CC cc=16
175
</PRE></TT>
176
 
177
<P CLASS=DESC>Move the "CC16" slider in MIOS Studio to check what happens! :-)
178
 
179
 
1097 tk 180
<H2> <IMG SRC="images/bullet.gif" ALT=""> Toggle me! </H2>
181
 
182
<P CLASS=DESC>Sometimes you probably want to hold the button state after the button has been pushed, and you want to turn it off by pushing it again. This toggling behaviour can be easily configured with the "button_mode" parameter:
183
 
1113 tk 184
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 185
EVENT_BUTTON id=1  fwd_id=LED:1  type=NoteOn key=36 range=0:127  button_mode=Toggle
186
</PRE></TT>
187
 
188
 
1095 tk 189
<H2> <IMG SRC="images/bullet.gif" ALT=""> Surprise me! </H2>
190
 
1097 tk 191
<P CLASS=DESC>Our last experiment with a single button ends with a small surprise: change the EVENT_BUTTON statement to:
1095 tk 192
 
1113 tk 193
<TT><PRE style="margin-left:50px; font-size:8pt">
1095 tk 194
EVENT_BUTTON id=1  fwd_id=LED:1  button_mode=OnOnly \
195
             type=SysEx stream="0xf0 0x00 0x00 0x7e 0x32 0x00 0x0d 0x40 0x57 0x6F 0x77 0x21 0xf7" \
196
             lcd_pos=1:1:1 label="Button #%3i: %3d"
197
</PRE></TT>
198
 
199
<P CLASS=DESC>...and have a look at the MIOS Terminal while pressing the button... ;-)
200
 
201
<P CLASS=DESC>Ok, this demonstration should also show you, that it's possible to send SysEx streams, and that multiple lines in the configuration file can be concatenated to a single command with the backslash (\) character.
202
 
203
 
1097 tk 204
<H2> <IMG SRC="images/bullet.gif" ALT=""> MIDIbox killed the Radio Star </H2>
205
 
206
<P CLASS=DESC>Let's get serious again! A typical usecase for buttons is to switch between different modes of an external device. If the mode has to be configured over a single CC event, you need to assign multiple buttons. In conjunction with LEDs it would be nice if only the LED which matches with the mode selection is lit, and that all others are off.</P>
207
 
208
<P CLASS=DESC>This behaviour can be configured with so called "Radio groups" (see also <A HREF="http://en.wikipedia.org/wiki/Radio_button" TARGET="_blank">this Wikipedia article about Radio Buttons</A>).
209
 
210
<P CLASS=DESC>So, let's try it! Following experiment requires 8 buttons connected to the first DIN shift register (input D0..D7), and 8 LEDs connected to the first DOUT shift register (output D7..D0):
211
 
1113 tk 212
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 213
EVENT_BUTTON id=  1  fwd_id=LED:1  type=CC chn=1 cc=16  button_mode=OnOnly  range= 0:0   radio_group=1
214
EVENT_BUTTON id=  2  fwd_id=LED:2  type=CC chn=1 cc=16  button_mode=OnOnly  range= 1:1   radio_group=1
215
EVENT_BUTTON id=  3  fwd_id=LED:3  type=CC chn=1 cc=16  button_mode=OnOnly  range= 2:2   radio_group=1
216
EVENT_BUTTON id=  4  fwd_id=LED:4  type=CC chn=1 cc=16  button_mode=OnOnly  range= 3:3   radio_group=1
217
EVENT_BUTTON id=  5  fwd_id=LED:5  type=CC chn=1 cc=16  button_mode=OnOnly  range= 4:4   radio_group=1
218
EVENT_BUTTON id=  6  fwd_id=LED:6  type=CC chn=1 cc=16  button_mode=OnOnly  range= 5:5   radio_group=1
219
EVENT_BUTTON id=  7  fwd_id=LED:7  type=CC chn=1 cc=16  button_mode=OnOnly  range= 6:6   radio_group=1
220
EVENT_BUTTON id=  8  fwd_id=LED:8  type=CC chn=1 cc=16  button_mode=OnOnly  range= 7:7   radio_group=1
221
</PRE></TT>
222
 
223
<P CLASS=DESC>They are all assigned to the same radio group 1 (note that up to 63 groups are available!).
224
 
225
<P CLASS=DESC>Now push the buttons one after another. Only the LED of the pressed buttons should be activated, all others will be turned off.
226
 
227
<P CLASS=DESC>Next step: send a CC16 event from MIOS Studio (take a slider above the virtual keyboard). The LEDs should change their state corresponding to the received value.
228
 
229
 
230
<H2> <IMG SRC="images/bullet.gif" ALT=""> Radio LEDs </H2>
231
 
232
<P CLASS=DESC>The same can be done without buttons, but only with LEDs. And it's also possible to select larger value ranges for a radio group!
233
 
234
<P CLASS=DESC>So, let's assume that 8 additional LEDs are connected to the second DOUT shift register, output D7..D0. We want to select the LED depeding on the incoming CC1 (modulation wheel) value. Just write:
235
 
1113 tk 236
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 237
EVENT_LED    id=  9                type=CC chn=1 cc= 1  range= 0:9  radio_group=2
238
EVENT_LED    id= 10                type=CC chn=1 cc= 1  range=10:19 radio_group=2
239
EVENT_LED    id= 11                type=CC chn=1 cc= 1  range=20:29 radio_group=2
240
EVENT_LED    id= 12                type=CC chn=1 cc= 1  range=30:39 radio_group=2
241
EVENT_LED    id= 13                type=CC chn=1 cc= 1  range=40:49 radio_group=2
242
EVENT_LED    id= 14                type=CC chn=1 cc= 1  range=50:59 radio_group=2
243
EVENT_LED    id= 15                type=CC chn=1 cc= 1  range=60:69 radio_group=2
244
EVENT_LED    id= 16                type=CC chn=1 cc= 1  range=70:79 radio_group=2
245
</PRE></TT>
246
 
247
<P CLASS=DESC>...and move the slider for "CC1: ModWheel" in MIOS Studio to select the different LEDs. :-)
248
 
249
 
250
<H2> <IMG SRC="images/bullet.gif" ALT=""> Rotate me! </H2>
251
 
252
<P CLASS=DESC>We are coming to the next control element: a <A HREF="http://www.midibox.org/dokuwiki/doku.php?id=encoders" TARGET="_blank">Rotary Encoder</A>.
253
 
254
<P CLASS=DESC>MIOS32 supports different type of encoders, we can mainly differentiate between "detented" and "non-detented". For detented encoders we also have to differ between various types, mainly depending on the state where it makes "click" ;-)
255
 
256
<P CLASS=DESC>The configuration of an encoder has to be done independent from the EVENT definition. E.g. take following configuration as an example:
257
 
1113 tk 258
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 259
ENC n=  1   sr=3 pins=0:1   type=non_detented
260
ENC n=  2   sr=3 pins=2:3   type=non_detented
261
ENC n=  3   sr=3 pins=4:5   type=non_detented
262
ENC n=  4   sr=3 pins=6:7   type=non_detented
263
ENC n=  5   sr=4 pins=0:1   type=non_detented
264
ENC n=  6   sr=4 pins=2:3   type=non_detented
265
ENC n=  7   sr=4 pins=4:5   type=non_detented
266
ENC n=  8   sr=4 pins=6:7   type=non_detented
267
</PRE></TT>
268
 
269
<P CLASS=DESC>In this example it's assumed, that 8 rotary encoders are connected to the third and fourth DIN shift register of your <A HREF="mbhp_din.html">MBHP_DINX4</A> module. Of course, you are free to use different DIN SRs for this, please adapt your configuration accordingly by changing the "sr=&lt;shift-register-number&gt;" assignment.
270
 
271
<P CLASS=DESC>Channel A and B of the encoder have to be connected to pin D0/D1, D2/D3, D4/D5 or D6/D7. The third pin has to be connected to ground. Some encoders have the ground at the middle pin, some others at the left or right pin - please consult the datasheet of the encoder that you bought!
272
 
273
<P CLASS=DESC>Without EVENT_ENC definition your encoder won't generate any MIDI event. But you will already be able to check, if encoder movements are notified by MIOS32. For this purpose, please activate the debug mode of MIDIbox NG in <B>the MIOS Terminal</B>:
1113 tk 274
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 275
set debug on
276
</PRE></TT>
277
 
278
When you are now moving the encoder, you should get debugging messages such as:
1113 tk 279
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 280
...
281
[472675.962] MBNG_ENC_NotifyChange(0, 1)
282
[472675.962] No event assigned to ENC id=1
283
[472676.035] MBNG_ENC_NotifyChange(0, 1)
284
[472676.035] No event assigned to ENC id=1
285
[472676.061] MBNG_ENC_NotifyChange(0, 1)
286
[472676.061] No event assigned to ENC id=1
287
...
288
</PRE></TT>
289
 
290
<P CLASS=DESC>on clockwise movements, and:
291
 
1113 tk 292
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 293
...
294
[472692.954] MBNG_ENC_NotifyChange(0, -1)
295
[472692.954] No event assigned to ENC id=1
296
[472692.969] MBNG_ENC_NotifyChange(0, -1)
297
[472692.969] No event assigned to ENC id=1
298
[472693.040] MBNG_ENC_NotifyChange(0, -1)
299
[472693.040] No event assigned to ENC id=1
300
...
301
</PRE></TT>
302
 
303
<P CLASS=DESC>on counter-clockwise movements of the first encoder (MIOS32 starts to count encoders from #0)
304
 
305
<P CLASS=DESC>This debugging mode already allows you to debug your configuration. E.g. if you are using a detented encoder, try:
306
<UL CLASS=CL>
307
  <LI><I>enc_mode=detented1</I>
308
  <LI>or <I>enc_mode=detented2</I>
309
  <LI>or <I>enc_mode=detented3</I>
310
</UL>
311
 
312
<P CLASS=DESC>and check if the increments are notified correctly after each "click".
313
 
314
<P CLASS=DESC>If the increments are inversed (-1 on clockwise movements), then you've probably swapped the connections between channel A and B of the encoder. In this case, please fix your hardware connections (this can't be changed in the configuration).
315
 
316
 
317
<H2> <IMG SRC="images/bullet.gif" ALT=""> Encoder: send MIDI - now! </H2>
318
 
319
<P CLASS=DESC>It's time to assign MIDI events to the encoders:
320
 
1113 tk 321
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 322
EVENT_ENC id=1  type=CC chn= 1 cc= 16
323
EVENT_ENC id=2  type=CC chn= 1 cc= 17
324
EVENT_ENC id=3  type=CC chn= 1 cc= 18
325
EVENT_ENC id=4  type=CC chn= 1 cc= 19
326
EVENT_ENC id=5  type=CC chn= 1 cc= 20
327
EVENT_ENC id=6  type=CC chn= 1 cc= 21
328
EVENT_ENC id=7  type=CC chn= 1 cc= 22
329
EVENT_ENC id=8  type=CC chn= 1 cc= 23
330
</PRE></TT>
331
 
332
<P CLASS=DESC>Your encoders will now send CC#16 .. CC#23 events, which should be displayed in the MIDI IN monitor of MIOS Studio!
333
 
334
<P CLASS=DESC>The big advantage of those encoders is, that they can take over incoming MIDI values, and modify them without the danger of "value jumps" when the encoder is moved again to modify the value (in other words: it will be on-synch to the remote device if it sends its own value changes as well).
335
 
336
<P CLASS=DESC>So, the next experiment will be, to send a CC#16 event to your MIDIbox NG, e.g. with the slider above the virtual keyboard in MIOS Studio.
337
 
338
<P CLASS=DESC>E.g. move the slider so that it sends CC#16 = 64 (check this with the MIDI OUT monitor of MIOS Studio).
339
 
340
<P CLASS=DESC>Now move the first encoder: it should increment/decrement from this received value!
341
 
342
 
343
<H2> <IMG SRC="images/bullet.gif" ALT=""> Display me! </H2>
344
 
345
<P CLASS=DESC>You already own a LCD? Fine - the next experiment will display some useful informations on the LCD instead of the static "Hello World!" string:
346
 
1113 tk 347
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 348
EVENT_ENC id=1  type=CC chn= 1 cc= 16  lcd_pos=1:1:1  label="ENC #%3i    %3d%B"
349
EVENT_ENC id=2  type=CC chn= 1 cc= 17  lcd_pos=1:1:1  label="ENC #%3i    %3d%B"
350
EVENT_ENC id=3  type=CC chn= 1 cc= 18  lcd_pos=1:1:1  label="ENC #%3i    %3d%B"
351
EVENT_ENC id=4  type=CC chn= 1 cc= 19  lcd_pos=1:1:1  label="ENC #%3i    %3d%B"
352
EVENT_ENC id=5  type=CC chn= 1 cc= 20  lcd_pos=1:1:1  label="ENC #%3i    %3d%B"
353
EVENT_ENC id=6  type=CC chn= 1 cc= 21  lcd_pos=1:1:1  label="ENC #%3i    %3d%B"
354
EVENT_ENC id=7  type=CC chn= 1 cc= 22  lcd_pos=1:1:1  label="ENC #%3i    %3d%B"
355
EVENT_ENC id=8  type=CC chn= 1 cc= 23  lcd_pos=1:1:1  label="ENC #%3i    %3d%B"
356
</PRE></TT>
357
 
358
<P CLASS=DESC>If you are confused about the strange "format specifiers" (starting with %), have a look into the <A HREF="midibox_ng_manual_ngc.html">.NGC format specification</A>, search for "label=&lt;string&gt;"
359
 
360
 
361
<H2> <IMG SRC="images/bullet.gif" ALT=""> Toy me! </H2>
362
 
363
<P CLASS=DESC>Let's play a bit with the labels. The example above overwrites the previous string whenever a different encoder is moved. But what if you want to get an oversight over all encoders - at least a vertical meter for each encoder?
364
 
365
<P CLASS=DESC>Try this one:
1113 tk 366
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 367
EVENT_ENC id=1  type=CC chn= 1 cc= 16  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:1:2)%B"
368
EVENT_ENC id=2  type=CC chn= 1 cc= 17  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:2:2)%B"
369
EVENT_ENC id=3  type=CC chn= 1 cc= 18  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:3:2)%B"
370
EVENT_ENC id=4  type=CC chn= 1 cc= 19  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:4:2)%B"
371
EVENT_ENC id=5  type=CC chn= 1 cc= 20  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:5:2)%B"
372
EVENT_ENC id=6  type=CC chn= 1 cc= 21  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:6:2)%B"
373
EVENT_ENC id=7  type=CC chn= 1 cc= 22  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:7:2)%B"
374
EVENT_ENC id=8  type=CC chn= 1 cc= 23  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:8:2)%B"
375
</PRE></TT>
376
 
377
<P CLASS=DESC>This will display the state of each encoder at the second LCD line - we selected it with the <I>@(&lt;lcd&gt;:&lt;X&gt;:&lt;Y&gt;)</I> specifier.
378
 
379
<H2> <IMG SRC="images/bullet.gif" ALT=""> Toy me remotely! </H2>
380
 
381
<P CLASS=DESC>You may have already noticed, that the LCD message isn't updated when the encoder value is changed from external (e.g. from a slider in MIOS Studio). The reason is, that incoming MIDI events won't trigger a LCD message by default (because this could be unwanted under certain situations).
382
 
383
<P CLASS=DESC>In order to update the LCD also in such situations, add the "fwd_to_lcd=1" parameter to your EVENT_* definition:
384
 
1113 tk 385
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 386
EVENT_ENC id=1  fwd_to_lcd=1  type=CC chn= 1 cc= 16  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:1:2)%B"
387
EVENT_ENC id=2  fwd_to_lcd=1  type=CC chn= 1 cc= 17  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:2:2)%B"
388
EVENT_ENC id=3  fwd_to_lcd=1  type=CC chn= 1 cc= 18  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:3:2)%B"
389
EVENT_ENC id=4  fwd_to_lcd=1  type=CC chn= 1 cc= 19  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:4:2)%B"
390
EVENT_ENC id=5  fwd_to_lcd=1  type=CC chn= 1 cc= 20  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:5:2)%B"
391
EVENT_ENC id=6  fwd_to_lcd=1  type=CC chn= 1 cc= 21  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:6:2)%B"
392
EVENT_ENC id=7  fwd_to_lcd=1  type=CC chn= 1 cc= 22  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:7:2)%B"
393
EVENT_ENC id=8  fwd_to_lcd=1  type=CC chn= 1 cc= 23  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:8:2)%B"
394
</PRE></TT>
395
 
396
<P CLASS=DESC>Now move the sliders in MIOS Studio and watch the LCD output! :-)
397
 
398
 
399
<H2> <IMG SRC="images/bullet.gif" ALT=""> Ring me! </H2>
400
 
401
<P CLASS=DESC>The next step - and this is really an advanced one - will be to use LED Rings for displaying the state of each rotary encoder.
402
 
403
<P CLASS=DESC>The <A HREF="midibox_ng_manual_hw.html">(non-existing) Hardware Chapter</A> describes, how the circuitry looks like.
404
 
405
<P CLASS=DESC>Actually it doesn't matter, if you are building the circuit based on the given schematic, or customize it, e.g. only for 8 LED Rings, or with a different number of LEDs per ring.
406
 
407
<P CLASS=DESC>The entry point to configure LED Rings is the <I>DOUT_MATRIX</I> command. It specifies the DOUT shift registers, which are used to access the LEDs in a matrix configuration. Matrix is good for such a usecase, because it saves a lot of digital output pins. The (small) drawback is, that LEDs are activated time multiplexed, which means that they are not so bright as if they would be driven directly (permanently) from a digital output pin. However, by using low-current LEDs this can be easily compensated. See it as an advantage: time multiplexing saves power (you still want to supply your MIDIbox NG via USB...)
408
 
409
<P CLASS=DESC>So, in following configuration example we assume a 16 LED Ring configuration, because this is the most common one that I used in previous projects like the <A HREF="http://www.ucapps.de/midibox16e/midibox16e.jpg" TARGET="_blank">MIDIbox16E</A>:
1113 tk 410
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 411
# LEDring configuration
412
DOUT_MATRIX n= 1   rows=16 sr_dout_sel1= 1 sr_dout_sel2= 2  sr_dout_r1= 3 sr_dout_r2= 4
413
</PRE></TT>
414
 
415
<P CLASS=DESC>Today we would prefer to use <A HREF="http://www.midibox.org/dokuwiki/doku.php?id=fairlightiii" TARGET="_blank">Fairlightiii's premade PCB solution</A> instead - more informations about this once I get my hands on the PCBs! :-)
416
 
417
<P CLASS=DESC>Anyhow, as you can see in the definitions above, the matrix allocates four DOUT shift registers to select the 16 rows, and to output the pattern. The pattern is predefined for 11 LEDs, but could also be changed for any number of LEDs with the <A HREF="midibox_ng_manual_ngc.html">LED_MATRIX_PATTERN</A> command.
418
 
419
<P CLASS=DESC>Now let's try following .NGC file - this is a copy&paste of my complete setup (for the case that you lost the thread... ;-)<BR>
420
<B>It might be necessary that you adapt the shift register (sr*=) definitions to your hardware, depending on which shift registers (SRs) your encoders and LED Rings are located!</B>
421
 
1113 tk 422
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 423
RESET_HW
424
 
425
LCD "%CHello"
426
 
427
# Encoder configuration
428
ENC n=  1   sr= 5  pins=0:1   type=non_detented
429
ENC n=  2   sr= 5  pins=2:3   type=non_detented
430
ENC n=  3   sr= 5  pins=4:5   type=non_detented
431
ENC n=  4   sr= 5  pins=6:7   type=non_detented
432
ENC n=  5   sr= 6  pins=0:1   type=non_detented
433
ENC n=  6   sr= 6  pins=2:3   type=non_detented
434
ENC n=  7   sr= 6  pins=4:5   type=non_detented
435
ENC n=  8   sr= 6  pins=6:7   type=non_detented
436
ENC n=  9   sr= 7  pins=0:1   type=non_detented
437
ENC n= 10   sr= 7  pins=2:3   type=non_detented
438
ENC n= 11   sr= 7  pins=4:5   type=non_detented
439
ENC n= 12   sr= 7  pins=6:7   type=non_detented
440
ENC n= 13   sr= 8  pins=0:1   type=non_detented
441
ENC n= 14   sr= 8  pins=2:3   type=non_detented
442
ENC n= 15   sr= 8  pins=4:5   type=non_detented
443
ENC n= 16   sr= 8  pins=6:7   type=non_detented
444
 
445
# LEDring configuration
446
DOUT_MATRIX n= 1   rows=16 sr_dout_sel1= 1 sr_dout_sel2= 2  sr_dout_r1= 3 sr_dout_r2= 4
447
 
448
# Encoder events
1113 tk 449
EVENT_ENC id= 1  fwd_id=LED_MATRIX:1   fwd_to_lcd=1  type=CC chn= 1 cc= 16  label="ENC #%3i    %3d@(1:1:2)%B"
450
EVENT_ENC id= 2  fwd_id=LED_MATRIX:2   fwd_to_lcd=1  type=CC chn= 1 cc= 17  label="ENC #%3i    %3d@(1:2:2)%B"
451
EVENT_ENC id= 3  fwd_id=LED_MATRIX:3   fwd_to_lcd=1  type=CC chn= 1 cc= 18  label="ENC #%3i    %3d@(1:3:2)%B"
452
EVENT_ENC id= 4  fwd_id=LED_MATRIX:4   fwd_to_lcd=1  type=CC chn= 1 cc= 19  label="ENC #%3i    %3d@(1:4:2)%B"
453
EVENT_ENC id= 5  fwd_id=LED_MATRIX:5   fwd_to_lcd=1  type=CC chn= 1 cc= 20  label="ENC #%3i    %3d@(1:5:2)%B"
454
EVENT_ENC id= 6  fwd_id=LED_MATRIX:6   fwd_to_lcd=1  type=CC chn= 1 cc= 21  label="ENC #%3i    %3d@(1:6:2)%B"
455
EVENT_ENC id= 7  fwd_id=LED_MATRIX:7   fwd_to_lcd=1  type=CC chn= 1 cc= 22  label="ENC #%3i    %3d@(1:7:2)%B"
456
EVENT_ENC id= 8  fwd_id=LED_MATRIX:8   fwd_to_lcd=1  type=CC chn= 1 cc= 23  label="ENC #%3i    %3d@(1:8:2)%B"
457
EVENT_ENC id= 9  fwd_id=LED_MATRIX:9   fwd_to_lcd=1  type=CC chn= 1 cc= 24  label="ENC #%3i    %3d@(1:9:2)%B"
458
EVENT_ENC id=10  fwd_id=LED_MATRIX:10  fwd_to_lcd=1  type=CC chn= 1 cc= 25  label="ENC #%3i    %3d@(1:10:2)%B"
459
EVENT_ENC id=11  fwd_id=LED_MATRIX:11  fwd_to_lcd=1  type=CC chn= 1 cc= 26  label="ENC #%3i    %3d@(1:11:2)%B"
460
EVENT_ENC id=12  fwd_id=LED_MATRIX:12  fwd_to_lcd=1  type=CC chn= 1 cc= 27  label="ENC #%3i    %3d@(1:12:2)%B"
461
EVENT_ENC id=13  fwd_id=LED_MATRIX:13  fwd_to_lcd=1  type=CC chn= 1 cc= 28  label="ENC #%3i    %3d@(1:13:2)%B"
462
EVENT_ENC id=14  fwd_id=LED_MATRIX:14  fwd_to_lcd=1  type=CC chn= 1 cc= 29  label="ENC #%3i    %3d@(1:14:2)%B"
463
EVENT_ENC id=15  fwd_id=LED_MATRIX:15  fwd_to_lcd=1  type=CC chn= 1 cc= 30  label="ENC #%3i    %3d@(1:15:2)%B"
464
EVENT_ENC id=16  fwd_id=LED_MATRIX:16  fwd_to_lcd=1  type=CC chn= 1 cc= 31  label="ENC #%3i    %3d@(1:16:2)%B"
1097 tk 465
</PRE></TT>
466
 
467
<P CLASS=DESC>This setup:
468
<UL CLASS=CL>
469
  <LI>configures the encoders and LED Ring hardware
470
  <LI>sends cc=16..31 whenever an encoder has been moved
471
  <LI>receives cc=16..31 to update the encoder value
472
  <LI>forwards the sent/received encoder value to the LED Ring
473
  <LI>and forwards the sent/received encoder value to the LCD
474
</UL>
475
 
476
 
477
<H2> <IMG SRC="images/bullet.gif" ALT=""> Bank me! </H2>
478
 
479
<P CLASS=DESC>You want to get more for the same price? Let's bank the encoders! :-)
1113 tk 480
<TT><PRE style="margin-left:50px; font-size:8pt">
481
# Example for Encoder 1
482
EVENT_ENC id= 1  hw_id=1  bank=1  fwd_id=LED_MATRIX:1   fwd_to_lcd=1  \
483
                                  type=CC chn= 1 cc= 16  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:1:2)%B"
1097 tk 484
 
1113 tk 485
EVENT_ENC id=17  hw_id=1  bank=2  fwd_id=LED_MATRIX:1   fwd_to_lcd=1  \
486
                                  type=CC chn= 1 cc= 32  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:1:2)%B"
487
 
488
EVENT_ENC id=33  hw_id=1  bank=3  fwd_id=LED_MATRIX:1   fwd_to_lcd=1  \
489
                                  type=CC chn= 1 cc= 48  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:1:2)%B"
490
 
491
EVENT_ENC id=49  hw_id=1  bank=4  fwd_id=LED_MATRIX:1   fwd_to_lcd=1  \
492
                                  type=CC chn= 1 cc= 64  lcd_pos=1:1:1  label="ENC #%3i    %3d@(1:1:2)%B"
1097 tk 493
</PRE></TT>
494
 
1113 tk 495
<P CLASS=DESC>These commands will map the first hardware encoder (<I>hw_id=1</I>) to the EVENT_ENC elements 1, 17, 33 and 49, which will send different CC numbers.
1097 tk 496
 
497
<P CLASS=DESC>You will need 4 buttons to switch between the banks - this is achieved by using so called "Meta Events" which don't issue MIDI output, but trigger internal functions instead:
1113 tk 498
<TT><PRE style="margin-left:50px; font-size:8pt">
1097 tk 499
EVENT_BUTTON id=  1  type=Meta   meta=SetBank button_mode=OnOnly range=1:1  lcd_pos=1:17:1 label="Bnk%q"
500
EVENT_BUTTON id=  2  type=Meta   meta=SetBank button_mode=OnOnly range=2:2  lcd_pos=1:17:1 label="Bnk%q"
501
EVENT_BUTTON id=  3  type=Meta   meta=SetBank button_mode=OnOnly range=3:3  lcd_pos=1:17:1 label="Bnk%q"
502
EVENT_BUTTON id=  4  type=Meta   meta=SetBank button_mode=OnOnly range=4:4  lcd_pos=1:17:1 label="Bnk%q"
503
</PRE></TT>
504
 
505
<P CLASS=DESC>A complete configuration example can be found in the SVN repository: <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fencbanks.ngc" TARGET="_blank">encbanks.ngc</A>
506
 
507
 
508
<P CLASS=DESC>This setup:
509
<UL CLASS=CL>
510
  <LI>configures the encoders and LED Ring hardware
511
  <LI>sends cc=16..31, cc=32..47, cc=48..63, cc=64..79 <B>depending on the bank selection</B> whenever an encoder has been moved
512
  <LI>always receives cc=16..79 independent from the bank selection. The LED Rings will be updated <B>according to the visible bank range</B>
513
  <LI>forwards the sent/received encoder value to the LED Ring
514
  <LI>and forwards the sent/received encoder value to the LCD <B>within the visible bank range</B>
515
</UL>
516
 
517
<P CLASS=DESC>So, this is actually what I started a century ago with the <A HREF="http://www.ucapps.de/midibox16e.html" TARGET="_blank">MIDIbox 16E</A> project. But with the MIDIbox NG approach we got a much more flexible solution - not to mention the advantages of USB-MIDI, OSC, SD Card as storage, no need to recompile the firmware on configuration changes, grouped Buttons/LEDs, support for NRPN and SysEx, more shift registers, more LCDs, even graphical LCDs (see below - in future - implemented but not documented at this place yet), etc, etc...</P>
518
 
1095 tk 519
<H2> <IMG SRC="images/bullet.gif" ALT=""> To be continued... </H2>
520
 
521
<P CLASS=DESC>...soon!</P>
522
 
523
FOOTER