Subversion Repositories svn.mios

Rev

Rev 1084 | Rev 1117 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed

HEADER 3 MIOS32 Bootloader for Newbies

<H1>MIOS32 Bootloader for Newbies</H1>

<P CLASS=INFO>The MIOS32 Bootloader allows you to upload a MIOS32 application into the internal flash memory of STM32 and LPC17 via USB or UART based MIDI interface.</P>

<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
<UL CLASS=CL>
  <LI><B>STM32:</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.
  <LI><B>LPC17:</B> use the LPC-Link which is part of LPCXPRESSO evaluation board to flash the bootloader via USB based JTAG
</UL>
This only has to be done once! The details are explained in the <A HREF="mios32_bootstrap_experts.html">Experts Section</A>.</P>

<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 STM32, ca. 20..40 kb/s on a LPC1769)!</P>

<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>

<H2>Starting the Bootloader</H2>

<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>

<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.</P>

<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:
<UL CLASS=CL>
  <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)
  <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), jumper J27 (Boot1) can be stuffed on the MBHP_CORE_STM32/MBHP_CORE_LPC17 module to select Bootloader Hold mode (J23 aka. Boot0 should *not* be stuffed!).<BR>
  Thereafter power-cycle the core.<BR>
  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").
  <LI>If the bootloader is running on a STM32 Primer, the Hold mode can be activated by soldering 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.</UL>
</P>

<H2>Code Upload</H2>

<TABLE ALIGN=CENTER CELLSPACING=20 CELLPADDING=0>

  <TR>
    <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>
    <TD><IMG SRC="images/1x1dot.gif" width=10 ALT=""></TD>
    <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>
  </TR>

</TABLE>

<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>

<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>
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>


<H2>Bootloader Parameter Storage</H2>

<P CLASS=DESC>The bootloader provides a permanent storage for parameters which are referenced
by (most) applications. These parameters can be customized from the MIOS Terminal
(part of MIOS Studio) by uploading this application.</P>

<P CLASS=DESC>Just type "help" in the MIOS Terminal to get a list of available commands.</P>

<P CLASS=DESC>Explanation of the most important parameters:
<UL CLASS=CL>
  <LI><B>fastboot:</B> normaly after power-on the bootloader waits for an upload request for 
  ca. 3 seconds before the actual application will be started.<BR>
  This is a fail-safe measure which is mainly relevant for developers who don't
  want to open their MIDIbox and stuff the "BSL Hold" jumper (J27) if the
  application crashed during the initialisation phase.<BR>

  However, for common users this wait phase shouldn't be really necessary, especially
  if they are using a stable application.<BR>

  Therefore: enter<BR>
<TT><PRE style="margin-left:50px">
     set fastboot 1
</PRE></TT>
  in the MIOS Terminal to skip this phase, and to start the application immediately!<BR>
  You will like this option! :-)<BR>

  Note that no MIDI upload request will be sent during power-on anymore!<BR>
  Please consider this when reading documentation about MIDI troubleshooting.


<LI><B>USB device name:</B> it's possible to assign a dedicated name for your MBHP_CORE_STM32
  or MBHP_CORE_LPC17 module which is used for the USB connection.<BR>

  This is especially useful if multiple MIDIboxes running with the same application
  are connected to your computer, so that you are able to differ between them.<BR>

  The USB name can be permanently changed with:<BR>
<TT><PRE style="margin-left:50px">
    set name <name>
</PRE></TT>
  e.g.
<TT><PRE style="margin-left:50px">
    set name MIDIbox SEQ V4 - 1
</PRE></TT>
  or
<TT><PRE style="margin-left:50px">
    set name MIDIbox SEQ V4 - 2
</PRE></TT>


<LI><B>Device ID:</B> this ID is relevant once multiple cores are available on the same MIDI port,
  or if you are using your MIOS32 based core as a USB<->MIDI / OSC<->MIDI gateway to a
  PIC based MBHP_CORE.<BR>

  MIOS Studio won't be able to differ between the cores in this case if they have the
  same Device ID, therefore it's recommended to change the Device ID of the MIOS32 core<BR>

  Enter:<BR>
<TT><PRE style="margin-left:50px">
     set device_id 127
</PRE></TT>
  to assign a new device id<BR>
  Again: this is only relevant if multiple cores are connected to the same MIDI port.<BR>

  IMPORTANT NOTE: don't change the Device ID if you are using MIOS Studio 2.2.1 or lower!
  Device IDs are properly supported with MIOS Studio 2.2.2 and higher!


<LI><B>LCD Type:</B> applications which are compiled with the "universal" LCD driver can handle
  various character/graphical LCD types and display dimensions.<BR>

  It's recommended to store these parameters of your MIDIbox in the bootloader info range.<BR>

  Following commands are available:<BR>
<TT><PRE style="margin-left:50px">
    lcd_types           lists all available LCD types and their appr. number
    set lcd_type <value>       the LCD type number (enter "lcd_types" to get a list of available types)
    set lcd_num_x <value>      number of LCDs in X direction
    set lcd_num_y <value>      number of LCDs in Y direction
    set lcd_width <value>      width of a single LCD (*)
    set lcd_height <value>     height of a single LCD (*)
</PRE></TT>

  (*) CLCDs: number of characters, GLCD: number of pixels<BR>

  Example: a single HD44780 based 2x20 character LCD is connected to your MIDIbox (default)<BR>
  Enter:<BR>
<TT><PRE style="margin-left:50px">
     lcd_type CLCD
     lcd_num_x 1
     lcd_num_y 1
     lcd_width 20
     lcd_height 2
</PRE></TT>

  Example2: two HD44780 based 2x40 character LCDs are connected to your MIDIbox<BR>
  Enter:<BR>
<TT><PRE style="margin-left:50px">
     lcd_type CLCD
     lcd_num_x 2
     lcd_num_y 1
     lcd_width 40
     lcd_height 2
</PRE></TT>

  Example3: five SSD1306 based 128x64 OLEDs are connected to your MIDIbox in vertical direction<BR>
  Enter:<BR>
<TT><PRE style="margin-left:50px">
     lcd_type GLCD_SSD1306
     lcd_num_x 1
     lcd_num_y 5
     lcd_width 128
     lcd_height 64
</PRE></TT>

  Please note: some applications (like MIDIbox SEQ V4) could overrule the predefined
  parameters if they can't handle smaller (or larger) LCD sizes.<BR>

  Please note also: some applications could have been released with a different
  LCD driver (MIOS32_LCD != "universal") which don't consider these parameters.
  It's up to the developer to document this limitation.<BR>
</UL>

FOOTER