View source for Getting Started - old, v0.56

<span style="font-size:88%">''by Yang/wdaehn, descriptions refer to firmware v0.56</span>''

You have a gimbal, the STorM32-BGC board, the IMU module and all cables. So what is next? This page is intended to guide you through the essential steps, and provides references to more specific pages in case you need to know more. Basically the steps are:

<div class="toclimit-2">__TOC__</div>

== Ordering Information ==
Things to order at minimum:
* STorM32-BGC board
* IMU module and matching cable 
* USB-to-TTL adapter

The STorM32-BGC board can be obtained from various shops. There are several hardware revisions around, but, frankly, they do not differ much. There is, e.g., nothing wrong with buying a v1.1 board, just keep in mind that some pins are placed differently here. A v1.3 board is used exemplary below.

Together with the board, buy also an IMU module and a matching cable from the same vendor. There are tons of different IMU modules available, and different connectors are in use. The plug on the STorM32 board is a so-called [http://www.molex.com/molex/products/family?key=picoblade&channel=products&chanName=family&pageTitle=Introduction Picoblade] connector (commonly but incorrectly often called JST 1.25 connector).

Finally, a USB-to-serial adapter with a matching cable is required for flashing the latest firmware. It can be any FTDI, CP2102, ... adapter, but NOT a PL2303-based adapter. Again, if you do not have one already, I recommend buying one together with the other parts. Personally I prefer those where the drivers come from the Windows Update Site automatically.

Things to watch out when comparing prices
* Bluetooth module included? The STorM32 board is designed for a HC06 Bluetooth module to be soldered on it. Then you can run the GUI on your laptop via Bluetooth. The range of these modules is modest, so do not expect that it allows to remotely monitor the gimbal values in flight. If in future a smartphone app should become available, this might be really cool for changing configurations, on the other hand, how often will you be doing that?
* Connectors soldered to it? Preinstalled connectors allow to simply plug in the motors and go. On the other hand, the RC and motor connectors are quite large, hence you may wish to place them differently or to solder motor cables directly to the board. Consider your preferences before buying. 
* IMU module and cable included? Is the IMU cable soft enough and of appropriate length?

'''Related wiki articles:'''
* [[Where to buy STorM32 boards]].
* [[Boards]].
* [[STorM32_FAQ#What_are_the_differences_between_the_boards.3F|FAQ: What are the differences between the boards?]]

== Flashing Firmware ==

Because the STorM32 board has a very active community, new firmware versions with new enhancements are released on about a monthly basis, so the first step will be to flash the newest firmware.

Your board may come or may not come with a firmware loaded; this depends on the vendor. In the first case you could skip the following steps and just install the GUI, but it is recommended to carry them out nevertheless, in order to get the latest firmware and GUI. In the latter case you must go through the steps; without firmware the board obviously would not function. The following description applies to both cases, only the USB driver gets installed by Win 7 in different steps; see the red warnings. It is crucial to NOT interrupt the USB driver install process. It can take several minutes, so please be patient.

In order to flash a new firmware the following steps are recommended.

# Get your USB-to-serial adapter to work by installing all Windows drivers as requested by the vendor. [[File:Usb-to-uart-driver.png|none|300px]]
# Unplug (!) the USB-to-serial adapter again.
# Connect the USB-to-serial adapter to the STorM32 board to the pins labeled RC (!). The firmware is not programmed via the UART port, not via USB, but via the RC pins. In other words, when the board is brought into the bootloader mode, the RC pins are re-assigned to the microcontroller's UART1; normally they are assigned to the PWM timer, and the UART pins are the mcu's UART0. All of this is a security measure to avoid people programming the board via e.g. Bluetooth and end up with an nonoperational board. [[File:Stom32-bgc-flashing-w-usbttladapter-connections-02.jpg|none|480px]]
# Connect the STorM32 board via USB to the computer. We are not using this connection yet, but we power the board via USB.<br>{{WARNING|If the board has already a firmware installed and this is the first-time connection to your PC, then Windows will install the USB driver for the STorM32 board. This can take quite some time. DO NOT interrupt the install process.}}
# Download the newest firmware, unzip it and run the GUI, in this example the o323BGCTool_v056.exe program. It does not matter what the current firmware installed is, you use the GUI that comes with the firmware zip file. Get the zip file from here: [[Downloads]].
# In the GUI select the {{GUI|Flash Firmware}} tab on the very right hand side and select the hardware revision of your board. This does change the firmware file to be used in the field below. [[File:Firmware_selector.png|none|300px]] 
# In step two, the middle of the screen, there is a {{GUI|Com Port}} selector for flashing. NOT the com port selector at the bottom! Click on the drop down box to see all currently available COM ports. Since we do not have connected the USB-to-serial adapter to the computer yet, the new one appearing when plugging in the adapter will be the one to use. Hence remember that list of ports to identify the new one in the next step. [[File:Firmware_comport1.png|none|300px]]
# Plugin the USB-to-serial adapter and click again on the drop down box of the serial connector for programming. Select the new one. [[File:Firmware_comport2.png|none|300px]]
# The board has two buttons, the boot and reset button. When the board is started, the very first thing the firmware does is checking if the boot button is currently pressed. If it is, the bootloader mode is entered, else the normal operation starts. The best way of entering the bootloader mode is hence to press the boot button and while it is pressed to press and release the reset button to initiate a hard reset. [[File:Firmware-bootloadermode.jpg|none|300px]]
# Check if the board is in bootloader mode or in operational mode. If the boards appears to be dead, then it is brought into bootloader mode successfully, if the LEDs are blinking, it is in normal operation and obviously the boot button was not pressed while the reset button was released. [[File:Firmware-bootloadermode-leds.jpg|none|300px]]
# Now the board is listening on the RC pins for serial data, the USB adapter is connected, and the correct COM port of the serial adapter is selected, so you can click on the {{GUI|Flash Firmware}} button. [[File:Firmware_start_flash.png|none|300px]]
# A DOS box will open and either return an error that the UART connection is not responding or a sequence of downloading and verifying the firmware is shown. [[File:Flash.png|none|300px]] {{WARNING|If this is a first-time flash of a "virgin" board, then Windows will install the USB driver. This can take quite some time. DO NOT interrupt the install process.}}
# After the reset, your board is fully operational and you may disconnect the USB-to-serial adapter.

In case you have troubles with the STorM32's USB driver, it can be found here: [http://www.st.com/web/en/catalog/tools/PF257938|STM download page].

'''Quick Trouble Shooting:''' In case the above did not work, typical traps when flashing are
* The board has no power - connect the board to the computer via USB to power it.
* The pins labeled UART are used for flashing - which is wrong, the RC pins should be used.
* Wrong serial port is selected in the tool.

It is also recommended to read the [[How to flash firmware]] page for trouble shooting.

'''Related wiki articles:'''
* [[How to flash firmware]].

== Checking Connection to the GUI ==

Let's next check if the STorM32-BGC is indeed operational, and communicates with the GUI. 

# If connected, disconnect a USB cable and/or USB-to-serial adapter. Click on the COM port selector in the left bottom and memorize the list. [[File:Board read 0.png|none|300px]]
# Then plug in the STorM32 board via the USB cable to power it. Either the matching driver was installed already or it will be installed now. Either way, once windows has installed the driver when clicking on the drop down for the COM port selector, it should now show an additional one.[[File:Board read 1.png|none|300px]]
# Jump back to the {{GUI|Main}} tab and click on {{GUI|Connect}} or {{GUI|Read}} to validate the connection with the board. [[File:Board_read_2.png|none|300px]]

== Hardware Setup ==

=== The Camera IMU ===

The camera IMU needs to be mounted such that it does measure all camera movements. Its actual position does not matter, behind the camera, on the pitch arm, below the camera,... anything will work. The only thing to watch out for is that its axes are aligned with the camera axes. Each axis has to be either horizontal or vertical. Just imagine that the sensor would read that the horizon is level but because of a misalignment the camera does hang slightly to one side and hence the horizon in the video is not level. 

=== Mounting the STorM32 Board ===

One of the outstanding features of the STorM32 board is its 2nd IMU support. In fact the board has such an IMU on-board already. To make use of it, the board needs to be mounted such that it measures the movements of the copter frame. The direction does not matter as long as it measures the frame's movements. In case this is not possible, either the 2nd IMU support has to be disabled, or another external IMU can be mounted to the frame and connected to the frame I2C connector, labeled I2C#2. As for the camera IMU, also the axes of the 2nd IMU have to be vertical or horizontal, respectively.

Related wiki articles:
* [[Using a 2nd IMU]].

=== Electric Connection and Insulation ===

The IMUs go to their corresponding I2C plugs: The camera IMU goes to the picoblade connector labeled I2C next to the USB connector. On the backside of the board is the I2C#2 connector for the optional frame IMU.

[[File:Stom32-bgc-v130-ports-and-connections-01.jpg|none|480px]]

One thing we found out the hard way is to never mount the board or the IMUs with metal screws and/or metal distance sleeves. Always use plastic ones. Not only does this help to avoid electrical problems but also the I2C bus can be sensitive to the nearby metal parts, leading to massive error rates on the I2C bus. Without a continuous readings of the IMU positions the entire purpose of the gimbal is forfeit.

Make also sure that the IMUs are mounted rigidly, so that they measure the actual position.

Related wiki articles:
* [[Dos and Don'ts]].
* [[Pins and Connectors]].
* [[I2C Error Compendium]].

=== Gimbal Mechanics ===

Before using a gimbal, it is absolutely necessary to balance it and to ensure minimum resistance to rotations (friction in bearings, stiff cables, etc). Any improper balance or resistance to rotation will make setting up the gimbal more difficult or even impossible. The goal shall be to rotate the camera in the gimbal and it should stay in that position by itself. In other words, the center of gravity should be in the center of all gimbal motor axes. Just imagine the camera's center of gravity is way below the pitch axis (looking with the camera up and down). It would act like a pendulum. So just because your copter does accelerate forward, the gimbal pitch motor has to hold against the mass inertia. You will need very strong motors and lots of energy which is a waste. On the other hand, if the gimbal is balanced properly, the motor only has to compensate the copter rotations, wind resistance and inertia when rotating the camera to point to somewhere else.

Related wiki articles:
* [[Tuning_Recipe#Balancing_the_Gimbal|Balancing the Gimbal]].

=== Powering the Gimbal ===

For the motors the 5 V supply of the USB bus is too low for sure. So, the motors will work only if a battery with sufficient voltage is connected. That is the reason why e.g. flashing the firmware is done using USB power only, as we do not want the motors to get power in that case. The battery connector can handle any voltage from 6 V to 18 V. Connecting the PC via the USB cable while the board is powered via a battery is no problem at all. The order does not matter, first USB then battery, or vice versa, both will work.

=== Motor Connectors ===

The board has three connectors for the motors labeled Mot0, Mot1 and Mot2. Before connecting any motor, it is a good idea to measure the resistance of the motor windings and the motor frame. The three motor cables should have an electrical resistance of 12 Ohm or more and be completely isolated from the motor housing. If the resistance is too low, the amount of amps flowing through the motor might be too high for the board driver. If one of the motor cables is connected to the motor housing, the entire gimbal and maybe even the frame gets the motor voltage.

The usage of the three connectors is
* Mot0: Pitch motor to point the camera up/down
* Mot1: Roll motor to stabilize the horizon
* Mot2: Yaw motor to turn the camera left/right

=== Summary ===

Now the motors are connected, the IMU(s) are connected, the battery power cable is ready, and its polarity double-checked.

{{WARNING|The picture is confusing as regards the pitch and roll motor connections, it should be pitch-roll-yaw.}}
[[File:0connections.JPG|none|480px]]

== First Configuration ==

{{COMMENT|Since v0.57e a new {{GUI|Configure Gimbal Tool}} is implemented, which further simplifies setup enormously (see [[Quick Start Guide]]). The first steps are however essentially identical to those described here.}} 

Now it's time to set the most important parameters, namely the IMU orientations and motor parameter values. Without that the controller can't perform the basic operations even. With the {{GUI|Configure Gimbal Tool}} this is very simple.

# Change to the {{GUI|Gimbal Configuration}} tab. There you can enter the values for the motor poles, the motor directions and the IMU orientation manually, or run the {{GUI|Configure Gimbal Tool}}. [[File:Gimbal config tool 1.png|none|300px]]
# In the welcome screen you can select what to configure, we want to do all and hence click on {{GUI|Continue}}. [[File:Gimbal config tool 2.png|none|300px]]
# Next we are asked to position the gimbal to look forward. So you manually adjust the camera so that it points into the forward direction of your copter. You might not be able to do that perfectly because of the motor magnets, 15° is more than enough. Once the camera is in forward position click on {{GUI|Continue}}. [[File:Gimbal config tool 3.png|none|300px]] [[File:Gimbal config tool forward.jpg| none | 500px]]
# Now you are asked to pitch the frame, the entire copter, by 45° downward, as if the goal would film the ground in front of the copter. So you lift the frame accordingly and both, frame and camera should point downwards. To be more precise, the camera should not move relative to the frame. If it does you should consider balancing the camera better. Anyway, the entire goal in this task is to get a clear reading of which axis of each IMU are all impacted by this 45° degree movement. The IMU does measure the acceleration values, as we are static its only acceleration is the earth gravity. For example the reading in the forward position might be x/y/z=0g/1g/0g. When pitching downward, the value could change to 0.7g/0.7g/0g and therefore we know that the pitch axis is along the z axis, its reading did not change (much). This plus the +/- sign allows to derive the IMU orientation by simply measuring it. [[File:Gimbal config tool 4a.png|none|300px]] [[File:Gimbal config tool 45.jpg| none | 500px]]
# Once the IMU orientation was read, the values are shown and we can continue with the next step. [[File:Gimbal config tool 4.png|none|300px]]
# This is just informational that the motor direction values are all being set to Auto. [[File:Gimbal config tool 5.png|none|300px]]
# Last step is the motor pole counts for each motor. This is again information you should get from the motor vendor, data like N12P14, meaning 14 poles. [[File:Gimbal config tool 6.png|none|300px]]
# With this the basic parameters are set but not stored permanently in the board. So you click on {{GUI|Okay}} to close the wizard. [[File:Gimbal config tool 7.png|none|300px]]
# The setup screen got updated now with the provided IMU, IMU2 and motor pole counts for each motor. All motors are disabled and the direction set to Auto. [[File:Gimbal config tool 8.png|none|300px]]
# In order to make these settings permanently stored, tick the checkbox next the {{GUI|Write}} button and the button will change its label to {{GUI|Write+Store}}. Press that button and the values get saved in the board's EEprom. [[File:Gimbal config tool 9.png|none|300px]]
# Attention: These values are used at startup only. Hence you have to reset the board! [[File:Gimbal config tool 10.png|none|300px]]

== First Startup ==

{{COMMENT|Since v0.57e a new {{GUI|Configure Gimbal Tool}} is implemented, which further simplifies setup enormously (see [[Quick Start Guide]]). The steps described here are now integrated into the new {{GUI|Configure Gimbal Tool}}.}} 

With above steps completed, plug in the battery in order to get power to the motors. Remember, the motor outputs had been disabled in the above step. Now position the camera to look forward by hand and then enable the motors. In the {{GUI|Setup}} tab check that the {{GUI|Pitch Usage}}, {{GUI|Roll Usage}} and {{GUI|Yaw Usage}} parameter fields are all set to {{GUIPARAM|disabled}}. Change them to {{GUIPARAM|normal}} individually. Or better, click on {{GUI|Enable all Motors}}, and write and store the changed setting. Without writing the values all you did is changing the values on your computer. Without the store the changes are not saved permanently in the controller's EEprom. The controller will now go through its initialization steps.

'''Initialization Steps:''' strtMOTOR - SETTLE - CALIBRATE - LEVEL - AUTODIR - RELEVEL - NORMAL
* {{PARAMNAME|strtMOTOR}}: The motors are turned on, and moved into the position specified by the startup motor position parameters.
* {{PARAMNAME|SETTLE}}: In order to calibrate, the gimbal has to be stable, it should not be moved. For a copter that is quite simple as the copter is on the ground. A handheld device needs to be put at a table to remain in position for a few seconds.
* {{PARAMNAME|CALIBRATE}}: Calibrates the sensors. Takes a second or so.
* {{PARAMNAME|LEVEL}}: This is the point where the motors will moved such to level the camera in pitch and roll axis. The yaw motor is under power, so you can feel some resistance, but it is not moved.
* {{PARAMNAME|AUTODIR}}: Here the motors are moved slightly around and from the sensor changes the controller determines the motor directions. 
* {{PARAMNAME|RELEVEL}}: Since autodir moved the camera, it is quickly brought back in a horizontal position.
* {{PARAMNAME|NORMAL}}: This is the final stage; the PID controller is activated and the gimbal is operational. Simply move the camera out of position by hand, move the frame,... whatever you do the camera should remain stable. With a 2nd IMU enabled you can pitch the camera indefinitely, you can yaw the camera indefinitely or roll the camera by maximal +-80° or so. More roll is not possible as then the pitch and yaw axes become aligned, and pitch and yaw movements cannot be distinguished anymore.

'''Led Signals''': The progress of the initialization is also indicated by the green LED on the board: During initialization it flashes with varying frequency; when initialization has finished and NORMAL state been reached, it goes solid. By the way, if beepes are activated, the motors will emit a sound at the end of initialization, which can be very convenient. The current state can also be seen in the GUI.

In the past, the first startup was often problematic for users and after lots of debugging the same root causes were identified: Motor directions, IMU orientation and occasionally the motor pole count. Therefore the {{GUI|Configure Gimbal Tool}} was implemented and all these problems should be gone now. Nevertheless some trouble shooting hints:

'''Quick Trouble Shooting:'''
* The gimbal controller levels the camera, but only very, very slowly: The gimbal is moved before the initialization has finished. Wait until the NORMAL state has been reach (green LED = solid) before moving the gimbal.
* The gimbal moves constantly around, never finding the level position: The pitch and roll motors are not connected to Mot0 (Pitch) and Mot1 (Roll) but reverse. Hence the control logic does measure that pitch has to be changed by -5°, applies the proper movement sequence to the motor but all that happens is that suddenly the roll value is off by -5°. Make sure the motors are connected correctly.
* Camera turns upside down or things like that: The IMU orientation is wrong.
* Gimbal starts shaking, makes high frequency noises and things like that: This would be normal as we have not yet tuned the PID values for the motor control loop. In case that happens, set for all motors the P, I and D values to very low numbers but not zero (P=0.10; I=5.0; D=0.0050) and write them to the board. This will cause the gimbal to be slow when correcting movements but at least you can prove all is functional.

We can save some time during the startup if we would speedup the leveling and the motor directions. For this we have three options in the {{GUI|Tools}} menu.
[[File:Gimbal config motor directions.png|none|300px]]

# {{GUI|Get Current Motor Directions}}: Since the gimbal is now in a normal operation, the AUTODIR phase was completed, it knows the directions. By selecting this menu the motor directions in the {{GUI|Gimbal Configuration}} tab are changed from {{GUIPARAM|auto}} to their actual direction {{GUIPARAM|normal}} or {{GUIPARAM|reverse}}.
# {{GUI|Get Current Pitch and Roll Motor Positions}}: Initially the gimbal does not know the current motor position. So it powers the motor's windings to assume a default position. Now that the gimbal is level, we know the motor positions default. Hence we can take the current position as {{GUIPARAM|Pitch Startup Motor Pos}} and {{GUIPARAM|Roll Startup Motor Pos}}
# {{GUI|Adjust Yaw Startup Motor Pos Parameter Tool}}: Yaw is a different story. The current yaw value cannot be zero'ed in as there is no sensor telling what "forward" means. Hence the motor start position is the only way but using what value? With the yaw tool you can manually move the gimbal in yaw to bring it into the forward position and then safe that as the {{GUIPARAM|Yaw Startup Motor Pos}}.

Don't forget to {{GUI|Write+Store}} these values permanently by ticking the checkbox next to the {{GUI|Write}} button to change its label and click that button.

'''Related wiki articles:'''
* [[STorM32_FAQ#How_does_Read.2C_Write.2C_and_Store_work.3F|FAQ: How does Read, Write, and Store work?]]

== Next Step - PID Tuning ==

At this point the gimbal may already stabilize the camera. However, usually, the camera is not yet stabilized perfectly, or the gimbal may even start to show weird shaking or make high frequency noises. This indicates that the PID values in the {{GUI|Main}} tab are not proper.

See the PID parameter [[Tuning Recipe|Tuning Recipe]] for adjusting those.