Subversion Repositories svn.mios

Rev

Rev 1139 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
585 tk 1
HEADER 3 MIOS32 Bootloader for Newbies
2
 
3
<H1>MIOS32 Bootloader for Newbies</H1>
4
 
1139 tk 5
<P CLASS=INFO>The MIOS32 Bootloader allows you to upload a MIOS32 application into the internal flash memory of STM32F1, STM32F4 and LPC17 via USB or UART based MIDI interface.</P>
585 tk 6
 
988 tk 7
<P CLASS=DESC>The big advantage of the so called bootstrap method is, that you don't need a programming device like JTAG or a COM port to install or update the software on your MIDIbox. Instead you can
8
<UL CLASS=CL>
1139 tk 9
  <LI><B>STM32F1:</B> buy a preprogrammed STM32F103RE from <A HREF="http://mbhp.avishowtech.com/buy.html" TARGET="_blank">SmashTV</A> (already presoldered on a <A HREF="mbhp_core_stm32.html">MBHP_CORE_STM32 PCB</A>) for a reasonable price, or you can ask a friend or a member of the <A HREF="http://forum.midibox.org" TARGET="_blank">MIDIbox Forum</A> who already owns the equipment for flashing the firmware into the STM32.
10
  <LI><B>STM32F4:</B> use the ST-Link which is part of STM32F4DISCOVERY evaluation board to flash the bootloader via USB based JTAG
988 tk 11
  <LI><B>LPC17:</B> use the LPC-Link which is part of LPCXPRESSO evaluation board to flash the bootloader via USB based JTAG
12
</UL>
13
This only has to be done once! The details are explained in the <A HREF="mios32_bootstrap_experts.html">Experts Section</A>.</P>
585 tk 14
 
1139 tk 15
<P CLASS=DESC>The bootloader brings benefit even for people who own this equipment, because the usage is faster and more comfortable; it's possible to upload new code on-the-fly without opening the MIDIbox case or plugging cables within a few number of seconds! Speaking about upload performance: an upload via USB MIDI is usually faster than via JTAG (ca. 13..17 kb/s on a STM32F1, ca. 50 kb/s on a STM32F4, ca. 20..40 kb/s on a LPC1769)!</P>
585 tk 16
 
988 tk 17
<P CLASS=DESC>In distance to MIOS8, the bootloader, MIOS32 and the application itself are provided as a single binary. This means: once any application has been flashed into the STM32/LPC17 chip, the bootloader will be available for future code uploads via MIDI as well.</P>
585 tk 18
 
19
<H2>Starting the Bootloader</H2>
20
 
1021 tk 21
<P CLASS=DESC>The bootloader is started on each STM32/LPC17 power-on reset, or during runtime if a special SysEx command is received. It sends an upload request, waits 3 seconds for a response (if the fastboot option isn't enabled), and thereafter starts the actual application. The temporary activation after power-on is provided as a fallback solution; it allows you to replace a faulty application which hangs up or blocks the MIDI interface.</P>
585 tk 22
 
1139 tk 23
<P CLASS=DESC>For MBHP_CORE_STM32 and MBHP_CORE_LPC17, upload via common MIDI cables (UART based MIDI interface) plugged into MIDI IN1/OUT1 sockets is always possible. This option is not supported by the STM32F4DISCOVERY based variant due to memory limitations in the bootloader range.</P>
585 tk 24
 
25
<P CLASS=DESC>Upload via USB (the fastest method) requires some special measures, as the USB MIDI device won't be enumerated fast enough by the host operating system (e.g. Windows) after power-on:
26
<UL CLASS=CL>
27
  <LI>upload via USB interface can be started during runtime if the application configured it for MIDI (this is mostly the case) and doesn't crash on incoming MIDI streams (should be mostly the case for released applications)
1139 tk 28
  <LI>if the application uses the USB interface for other purposes (e.g. Virtual COM), or the upload doesn't work for any reason (e.g. due to a bug during program development), the so called "boot hold" mode can be enabled during power-on. Once in hold mode, a special USB MIDI device will be available (called "MIOS32 Bootloader") to upload code. The application will be started once the jumper has been removed again. It is recommended to power-cycle the core thereafter to get a proper USB connection (under Windows), and to restart MIOS Studio, so that it sees the new USB MIDI port ("MIOS32" instead of "MIOS32 Bootloader").<BR>
29
How to enter this mode:
30
<UL CLASS=CL>
31
  <LI><B>MBHP_CORE_STM32:</B> stuff jumper J27 (Boot1) module to select the bootloader hold mode (J23 aka. Boot0 should *not* be stuffed!), thereafter power-cycle the core.
32
  <LI><B>STM32 Primer:</B> solder a small cable between the boot1 signal on R48 and Ground as shown <A HREF="">in this picture</A>. However, the Primer contains an integrated debug interface which makes it easy to recover the MIOS32 installation w/o this measure.
33
  <LI><B>MBHP_CORE_LPC17:</B> stuff jumper J27 (BL Hold) to select the bootloader hold mode, thereafter power-cycle the core.
34
  <LI><B>MBHP_CORE_STM32F4 and STM32F4DISCOVERY:</B> press and hold the blue "User" button, trigger the black "Reset" button shortly. This will restart the core and enforce bootloader mode as long as the blue "User" button is pressed.
35
  </UL>
36
</UL>
585 tk 37
</P>
38
 
39
<H2>Code Upload</H2>
40
 
41
<TABLE ALIGN=CENTER CELLSPACING=20 CELLPADDING=0>
42
 
43
  <TR>
897 tk 44
    <TD><A HREF="mios_download.html" TARGET="_blank"><IMG SRC="mios_studio/mios_studio_icon.png" WIDTH=128 HEIGHT=128 ALT="Link to MIOS Studio"></A></TD>
585 tk 45
    <TD><IMG SRC="images/1x1dot.gif" width=10 ALT=""></TD>
897 tk 46
    <TD><SPAN CLASS=NORM> <A HREF="mios_studio.html" TARGET="_blank">Download MIOS Studio</A> - this is a Juce based environment with MIOS specific tools which runs on PCs and Macs.</SPAN></TD>
585 tk 47
  </TR>
48
 
49
</TABLE>
50
 
51
<P CLASS=DESC>If no error has been reported by the upload tool (to ensure this, scroll up the log window and check all status messages), it can be assumed that the application has been installed successfully. Note that it is not possible to run multiple applications in parallel - a new application will always overwrite the old one.</P>
52
 
53
<P CLASS=DESC>Note: if you are using the USB interface under Windows, it is required to restart MIOS Studio whenever the core has been power-cycled, resp. the USB MIDI Device has been enumerated again. You probably know this issue from your other USB MIDI interfaces as well. This measure isn't required when you are using MacOS or Linux.<BR>
588 tk 54
Another typical Windows issue: instead of "MIOS32", the USB device is probably called "Audio Device" or in german "Audioger&auml;t", and you have to close all MIDI applications which could access the same port, as the legacy Microsoft MIDI USB driver isn't multi-client capable (no issue under MacOS/Linux).</P>
585 tk 55
 
56
 
1021 tk 57
<H2>Bootloader Parameter Storage</H2>
585 tk 58
 
1021 tk 59
<P CLASS=DESC>The bootloader provides a permanent storage for parameters which are referenced
60
by (most) applications. These parameters can be customized from the MIOS Terminal
1117 tk 61
(part of MIOS Studio) by uploading the <B>mios32_bootloader</B> update application.</P>
1021 tk 62
 
1117 tk 63
<P CLASS=DESC>After the upload of this app, type "help" in the MIOS Terminal to get a list of available commands.</P>
1021 tk 64
 
1119 tk 65
<P CLASS=DESC><B>IMPORTANT:</B> parameter changes have to be stored with the "store" command before uploading a new application, otherwise they will get lost!<BR>
66
These commands are only available in the mios32_bootloader update app, and not in MIDIO128, MIDIbox SEQ, MIDIbox NG or similar - in order to change the parameter, just upload the update app, modify the configuration, and upload the actual firmware for your MIDIbox again.</P>
67
 
1021 tk 68
<P CLASS=DESC>Explanation of the most important parameters:
585 tk 69
<UL CLASS=CL>
1021 tk 70
  <LI><B>fastboot:</B> normaly after power-on the bootloader waits for an upload request for
71
  ca. 3 seconds before the actual application will be started.<BR>
72
  This is a fail-safe measure which is mainly relevant for developers who don't
73
  want to open their MIDIbox and stuff the "BSL Hold" jumper (J27) if the
74
  application crashed during the initialisation phase.<BR>
585 tk 75
 
1021 tk 76
  However, for common users this wait phase shouldn't be really necessary, especially
77
  if they are using a stable application.<BR>
787 tk 78
 
1021 tk 79
  Therefore: enter<BR>
1113 tk 80
<TT><PRE style="margin-left:50px">
1021 tk 81
     set fastboot 1
1119 tk 82
     store
1113 tk 83
</PRE></TT>
1021 tk 84
  in the MIOS Terminal to skip this phase, and to start the application immediately!<BR>
85
  You will like this option! :-)<BR>
787 tk 86
 
1021 tk 87
  Note that no MIDI upload request will be sent during power-on anymore!<BR>
88
  Please consider this when reading documentation about MIDI troubleshooting.
585 tk 89
 
1119 tk 90
</UL>
1183 tk 91
 
1119 tk 92
<UL CLASS=CL>
1117 tk 93
  <LI><B>single_usb:</B> use this option if you are working with a Windows PC which can't handle
94
     multiple USB ports correctly.<BR>
95
     E.g. applications like <A HREF="midio128.html">MIDIO128</A>,
96
     <A HREF="midibox_seq.html">MIDIbox SEQ</A> or <A HREF="midibox_ng.html">MIDIbox NG</A> enable
97
     4 USB ports by default. Certain Windows versions (such as Windows XP) are failing:
1119 tk 98
     sometimes MIDI events get stucked, MIOS Studio filebrowser operations abort with an error message, etc.<BR>
99
     Even the installation of the GM5 USB MIDI driver doesn't help (which sometimes solves the issues under Windows7),
1117 tk 100
     or causes new issues when multiple core modules are connected.<BR>
101
     As a workaround, it's possible to enforce that only a single USB port is enabled:
102
<TT><PRE style="margin-left:50px">
103
     set single_usb 1
1119 tk 104
     store
1117 tk 105
</PRE></TT>
1119 tk 106
     This should solve the windows USB MIDI issues - with the drawback of the reduced functionality.
1183 tk 107
</UL>
1117 tk 108
 
1183 tk 109
<UL CLASS=CL>
110
  <LI><B>enforce_usb_device:</B> this option has only an effect on core modules which support USB Host mode such as
111
     the <A HREF="mbhp_core_stm32f4.html">MBHP_CORE_STM32F4</A> module.<BR>
112
     If set to 1, USB device mode will be selected regardless of the cable type A or B.
113
     If set to 0 (default), USB host mode will be selected with A type cables, and USB device mode with B type cables.<BR>
114
     This type of selection is also known as USB OTG (on-the-go).<BR>
115
     The usage of the default setup is normally save, "set enforce_usb_device 1" only if you are using an "unusual" cable.<BR>
116
     Note that setting this parameter could lead to a dilemma: it can only be set with a bidirectional MIDI connection between the core module and the
117
     MIOS Studio terminal. If you don't own a Micro-USB B type cable to establish this connection, the only possibility to change this parameter
118
     is a "traditional" MIDI connection via MIDI IN/OUT between the core module and your PC/Mac!<BR>
119
     If you don't own a MIDI interface for such a connection, it's cheaper to buy the right Micro-USB cable - once you've changed the parameter, you can use the "improper" cable for your core!
120
</UL>
1117 tk 121
 
1119 tk 122
<UL CLASS=CL>
1021 tk 123
<LI><B>USB device name:</B> it's possible to assign a dedicated name for your MBHP_CORE_STM32
124
  or MBHP_CORE_LPC17 module which is used for the USB connection.<BR>
585 tk 125
 
1021 tk 126
  This is especially useful if multiple MIDIboxes running with the same application
127
  are connected to your computer, so that you are able to differ between them.<BR>
128
 
129
  The USB name can be permanently changed with:<BR>
1113 tk 130
<TT><PRE style="margin-left:50px">
1119 tk 131
     set name <name>
1113 tk 132
</PRE></TT>
1021 tk 133
  e.g.
1113 tk 134
<TT><PRE style="margin-left:50px">
1119 tk 135
     set name MIDIbox SEQ V4 - 1
136
     store
1113 tk 137
</PRE></TT>
1021 tk 138
  or
1113 tk 139
<TT><PRE style="margin-left:50px">
1119 tk 140
     set name MIDIbox SEQ V4 - 2
141
     store
1113 tk 142
</PRE></TT>
1021 tk 143
 
144
 
1119 tk 145
</UL>
146
<UL CLASS=CL>
1021 tk 147
<LI><B>Device ID:</B> this ID is relevant once multiple cores are available on the same MIDI port,
148
  or if you are using your MIOS32 based core as a USB<->MIDI / OSC<->MIDI gateway to a
149
  PIC based MBHP_CORE.<BR>
150
 
151
  MIOS Studio won't be able to differ between the cores in this case if they have the
152
  same Device ID, therefore it's recommended to change the Device ID of the MIOS32 core<BR>
153
 
154
  Enter:<BR>
1113 tk 155
<TT><PRE style="margin-left:50px">
1021 tk 156
     set device_id 127
1119 tk 157
     store
1113 tk 158
</PRE></TT>
1021 tk 159
  to assign a new device id<BR>
160
  Again: this is only relevant if multiple cores are connected to the same MIDI port.<BR>
1119 tk 161
  Changing the device ID is not required if the MIDIboxes are accessed from dedicated USB MIDI ports!<BR>
1021 tk 162
 
1119 tk 163
  <B>IMPORTANT NOTE:</B> don't change the Device ID if you are using MIOS Studio 2.2.1 or lower!
1021 tk 164
  Device IDs are properly supported with MIOS Studio 2.2.2 and higher!
165
 
166
 
1119 tk 167
</UL>
168
<UL CLASS=CL>
1021 tk 169
<LI><B>LCD Type:</B> applications which are compiled with the "universal" LCD driver can handle
170
  various character/graphical LCD types and display dimensions.<BR>
171
 
172
  It's recommended to store these parameters of your MIDIbox in the bootloader info range.<BR>
173
 
174
  Following commands are available:<BR>
1113 tk 175
<TT><PRE style="margin-left:50px">
1119 tk 176
     lcd_types           lists all available LCD types and their appr. number
177
     set lcd_type <value>       the LCD type number (enter "lcd_types" to get a list of available types)
178
     set lcd_num_x <value>      number of LCDs in X direction
179
     set lcd_num_y <value>      number of LCDs in Y direction
180
     set lcd_width <value>      width of a single LCD (*)
181
     set lcd_height <value>     height of a single LCD (*)
182
     store
1113 tk 183
</PRE></TT>
1021 tk 184
 
185
  (*) CLCDs: number of characters, GLCD: number of pixels<BR>
186
 
187
  Example: a single HD44780 based 2x20 character LCD is connected to your MIDIbox (default)<BR>
188
  Enter:<BR>
1113 tk 189
<TT><PRE style="margin-left:50px">
1021 tk 190
     lcd_type CLCD
191
     lcd_num_x 1
192
     lcd_num_y 1
193
     lcd_width 20
194
     lcd_height 2
1119 tk 195
     store
1113 tk 196
</PRE></TT>
1021 tk 197
 
198
  Example2: two HD44780 based 2x40 character LCDs are connected to your MIDIbox<BR>
199
  Enter:<BR>
1113 tk 200
<TT><PRE style="margin-left:50px">
1021 tk 201
     lcd_type CLCD
202
     lcd_num_x 2
203
     lcd_num_y 1
204
     lcd_width 40
205
     lcd_height 2
1119 tk 206
     store
1113 tk 207
</PRE></TT>
1021 tk 208
 
209
  Example3: five SSD1306 based 128x64 OLEDs are connected to your MIDIbox in vertical direction<BR>
210
  Enter:<BR>
1113 tk 211
<TT><PRE style="margin-left:50px">
1021 tk 212
     lcd_type GLCD_SSD1306
213
     lcd_num_x 1
214
     lcd_num_y 5
215
     lcd_width 128
216
     lcd_height 64
1119 tk 217
     store
1113 tk 218
</PRE></TT>
1021 tk 219
 
220
  Please note: some applications (like MIDIbox SEQ V4) could overrule the predefined
221
  parameters if they can't handle smaller (or larger) LCD sizes.<BR>
222
 
223
  Please note also: some applications could have been released with a different
224
  LCD driver (MIOS32_LCD != "universal") which don't consider these parameters.
225
  It's up to the developer to document this limitation.<BR>
226
</UL>
227
 
1117 tk 228
 
229
<H2> Working under MacOS? </H2>
230
 
231
<P CLASS=DESC>The USB MIDI implementation of MacOS is perfectly working, regardless of the number of USB MIDI ports!
232
 
233
<P CLASS=DESC>So far we only noticed a minor issue when an app changes the number of USB MIDI ports or the device name. Such changes won't be taken over automatically, instead you've to delete the old interface description in the Audio-MIDI-Setup:
234
<UL CLASS=CL>
235
  <LI>start the Audio-MIDI-Setup of MacOS (e.g. search for "audio-midi" with Spotlight)
236
  <LI>disconnect the core module from USB
237
  <LI>delete the interface in the Audio-MIDI-Setup
238
  <LI>connect the core module to USB again
239
</UL>
240
 
241
<P CLASS=DESC>Thereafter you should see an interface with the new names and the right number of USB MIDI Ports:
242
<A HREF="mios32/macos_midi_setup.png"><IMG SRC="mios32/macos_midi_setup.png" WIDTH=550></A>
243
 
585 tk 244
FOOTER