making a start on docs

docs/src/Getting Started.adoc

@@ -0,0 +1,438 @@
+:lang: en
+
+= STMBL Getting Started Guide
+
+== Description
+
+STMBL is a motor drive controlled by the STM32 microprocessor. It can 
+power motors of up to 2.2kW and up to around 350V DC bus voltage. 
+
+The name "STMBL" is based on the combination of the STM32 microprocessor
+and BrushLess motor. However the drive is also capable of powering AC
+induction motors. The hardware is also capable of driving 3-phase
+stepper motors.
+
+The drive is configurable for a wide range of command and feedback types
+through a HAL layer analagous to that used by 
+http://linuxcnc.org/docs/2.7/html/hal/intro.html[LinuxCNC]. 
+
+Supported command interfaces are:
+
+* Mesa Smart-Serial
+* Step-Dir
+* Quadrature
+* Serial
+
++/-10V control is not supported, though the hardware capability exists.
+
+Supported feedback interfaces are:
+
+* Encoder
+* Resolver
+* sin/cos 1vpp
+* Mitsubishi absolute encoder
+* Yaskawa absolute encoder
+* Sick Hyperface
+* Sanyo Denki absolute encoder
+
+Encoder power is 5V by default but 12V can be selected by jumper pads on
+the PCB. 
+
+In addition to motor control and feedback each STMBL drive has two
++/-30V analogue inputs and three 24V / 2A digital outputs. 
+
+== Anatomy of the STMBL
+
+The STMBL consists of two separate PCBs (though they are made as one,
+assembled and then split to be connected in the manner shown below. 
+The vertical (top) board is the Low Voltage (LV) board and this handles
+the command, feedback and configuration tasks. The STM32F4
+microprocessor is in charge of these tasks. 
+The lower board is the
+high-voltage (HV) board and this is where the power driver is situated.
+The only connection between the two boards is a serial connection
+through a 5kV isolation IC. To make this possible there is a second
+STM32 chip on the lower board. This is an STM32F3 and is referred to as
+the "F3" in the remainder of this document. The processor on the upper
+board is referred to as "F4".
+
+image::images/ISO1.svg[]
+
+The connectors on the HV board are 5.08mm pitch. Those on the LV board
+are 3.5mm pitch.  Mating part numbers are:
+
+* HV Power: https://octopart.com/1757019-phoenix+contact-789[1757019]
+* HV Motor: https://octopart.com/1757022-phoenix+contact-902[1757022] or
+https://octopart.com/1792760-phoenix+contact-29279[1792760]
+* LV Power: https://octopart.com/1840366-phoenix+contact-6675[1840366] or
+https://octopart.com/1862852-phoenix+contact-118535[1862852]
+* IO: https://octopart.com/1840405-phoenix+contact-14126[1840405] or
+https://octopart.com/1862894-phoenix+contact-79205[1862894]
+
+If preferred 2 x 3 position or 3 x 2 position plugs can be inserted in
+the 6-position sockets. 
+
+Logic power to the LV board should be 24V. A green LED will light
+adjacent to the socket when power is supplied.
+
+WARNING: The LV board is safe up to about 30V but take care that 0V is
+common with the PC GND before connecting a USB cable. 
+
+Motor power should be 30 to 350V, though the logic parts of the HV
+board may work at 24V for firmware flashing etc. Again a green LED
+adjacent to the connector confirms that the board is powered-up.
+
+WARNING: The HV and LV boards are isolated in normal use but it is easy
+to accidentally connect them. One way to do this is via USB cables which
+can easily tie GND lines together through the setup PC. It is imperative
+that the HV board should be powered from an isolated (and preferably
+low voltage) supply when flashing firmware. 
+
+image::images/ISO2.svg[]
+
+The command and feedback connectors use standard 8P8C (RJ45) connectors
+and standard CAT5 or CAT6 cables can be conveniently used. To connect
+to cables with larger conductors than supported by CAT5 it is possible
+to use, for example,
+https://octopart.com/j00026a2001-telegärtner-24873031[Industrial CAT6a]
+connectors which can accept core wires up to 1.6mm and overall cable
+diameters up to 9.0mm.
+
+Feedback 0 will typically be the encoder or resolver mounted on the
+motor and feedback 1 can be used to connect either Hall sensors for
+initial commutation or (potentially) scales mounted directly to the
+axes. See the <<Pinouts>> section of this document for pin assigments
+and typical wiring colour codes. 
+
+The 6-way socket below the 24V logic power connector contains the three
+digital outputs. These are current-sinking (switch-to-GND) and each is
+adjacent to a 24V suppply pin. DIO0 (nearest the top) is the one that is
+typically used to operate the holding brake on motors so-equipped. 
+
+On the top of the drive are two analogue inputs, with 0V and 24V on
+either side to that a potentiometer can be connected. These are
+typically used as variable-threshold digital inputs and are used, for
+example, for axis limit switches. However it is relatively simple to
+configure them for other uses in the HAL layer. 
+
+Three LEDS on top of the unit indicate drive status. Red displays error
+codes (using <<Blink Codes,blink codes>>). Amber indicates that all is well but the
+drive is not enabled, and green shows that the drive is active and
+operating normally. 
+
+If no LEDs on the top of the board are illuminated, and the green power
+LEDs near the power connectors _are_ illuminated then it is probably
+necessary to <<Flashing Firmware, flash the firmware>>. If there are
+LEDs lit on top of the drive then it is probably safe to assume that
+firmware is loaded. 
+
+== HAL (Hardware Abstraction Layer)
+
+STMBL uses a Hardware abstraction layer to configure the drive for
+different types of motor, feedback and operation mode.
+This is conceptually similar to the HAL in LinuxCNC but the format and
+cmmands are different. Also, all pins are floating point so no data
+conversion is needed. 
+
+An Application called <<Servoterm>> is used to interact with the HAL
+interface and configure the drive. You will need to install and launch
+this before it is possible to configure the STMBL.
+
+STMBL HAL configuration does not use any commands other than the = sign
+and the <<Servoterm Commands,servoterm commands>>
+
+Assuming that there is already a motor connected to the drive and that
+the drive it powered up the <<Servoterm>> display should already be
+indicating the motor position feedback. Rotating the motor shaft by hand
+might produce something like:
+
+image::images/servoterm3.png[]
+
+Though it equally well might not if the configuration is set up for a
+resolver and the motor has an encoder. 
+
+It should be possible to make the motor turn at this point without any
+further configuration. The commands that follow will set the hv0 module
+up to simply rotate the motor open-loop in direct-mode. (like a stepper
+motor) with an excitation current of 0.5A. This should be safe for most
+motors that the STMBL is a good match for, but you should choose your
+own value. For an explanation of direct and quadrature current see the
+section on <<Motor Control Basics>>
+
+`hv0.pos = sim0.vel`
+`hv0.d_cmd = 0.5`
+`hv0.en = 1`
+
+The rotation speed can be altered by changing the sim0 frequency:
+
+`sim0.freq = 5`
+
+STMBL v4 HAL contains a number of components that have built-in linking
+behaviour. 
+
+
+=== HAL modules
+The Servoterm command `show` will list all the HAL modules that can be
+loaded (whereas `list` will show all those that currently are loaded)
+
+The modules available are as follows (the link will take you to the
+reference section for each component)
+
+
+<<HAL Reference#acim_ttc,acim_ttc>> - The module used for AC induction
+motors (cf pmsm) ttc is Torque to Current+
+<<HAL Reference#adc,adc>> - Analogue to digital converter for Resolver
+feedback. Outputs the sine and cosine amplitudes. +
+<<HAL Reference#conf,conf>> - A module used to supply config data to
+other modules. +
+<<HAL Reference#curpid,curpid>> - No idea +
+<<HAL Reference#dc,dc>> - No idea +
+<<HAL Reference#dc_limits,dc_limits>> - no idea +
+<<HAL Reference#dc_ttc,dc_ttc>> - no idea +
+<<HAL Reference#dq,dq>> - not much idea +
+<<HAL Reference#enc_cmd,enc_cmd>> - Used to supply position commands
+through quadrature signals +
+<<HAL Reference#enc_fb,enc_fb>> Encoder counter, converts AB quadrature
+and index on FB0 connector to motor position +
+<<HAL Reference#encm,encm>> +
+<<HAL Reference#fanuc,fanuc>> Converts Fanuc 4-channel commutation
+signals +
+<<HAL Reference#fault,fault>> Handles the checking and distribution of
+fault information and reactons between the modules +
+<<HAL Reference#fb_switch,fb_switch>> This module arbitrates between
+commutation inputs for motors where UVW (Hall) sensors are suppplied in
+addition to an encoder. +
+<<HAL Reference#hal_test,hal_test>> Something to do with testing, I 
+assume +
+<<HAL Reference#hv,hv>> This module controls the HV board, provides the
+current and voltage commands to the H-bridge. +
+<<HAL Reference#idq,idq>> - Something to do with commutation +
+<<HAL Reference#idx_home,idx_home>> - Handles homing to the index pulse +
+<<HAL Reference#iit,iit>> - No idea +
+<<HAL Reference#io,io>> - Controls the IO, both input and output. +
+Including the feedback and command connector LEDs. Also mirrors ABZ and
+UVW states. +
+<<HAL Reference#linrev,linrev>> - Converts linear position into motor
+single-turn command positions and vice-versa. +
+<<HAL Reference#move,move>> - Surely does something +
+<<HAL Reference#o_fb,o_fb>> - A feedback, but from where? +
+<<HAL Reference#pe,pe>> - No idea.
+<<HAL Reference#pid,pid>> - The position PID controller. +
+<<HAL Reference#pmsm,pmsm>> - Permananet Magnet Servo Motor control
+module. Required for nearly all servo motors. +
+<<HAL Reference#pmsm_limits,pmsm_limits>> - Controls the limits for
+pmsm, used to clamp the PID +
+<<HAL Reference#pmsm_ttc,pmsm_ttc>> - PMSM torque to current
+calculation +
+<<HAL Reference#psi,psi>> - Motor Constant calculations. Nm/A +
+<<HAL Reference#ramp,ramp>> - Ramp? +
+<<HAL Reference#res,res>> - Resolver module for motors that use them.
+Calculates rotor position from the sine-cosine of ADC and generates the
+excitation. +
+<<HAL Reference#reslimit,reslimit>> - Limitation for the Resolver
+module +
+<<HAL Reference#rev,rev>> - Very important + 
+<<HAL Reference#scale,scale>> - A scaling utility function. +
+<<HAL Reference#sim,sim>> - Provides a set of waveforms useful for motor
+characterisation and testing. +
+<<HAL Reference#spid,spid>> - Simple PID. Usable but not used +
+<<HAL Reference#sserial,sserial>> - Handles communication through the 
+Mesa Electronics Smart Serial interface. Takes digital (floating point
+position and velocity commands and returns digital position and current
+feedback data. Also handles STMBL GPIO to LinuxCNC HAL.  +
+<<HAL Reference#stp,stp>> - Simple Trajectory Plannner +
+<<HAL Reference#svm,svm>> - Space Vector Modulation +
+<<HAL Reference#term,term>> - Graphing terminal in Servoterm. +
+<<HAL Reference#uf,uf>> - Good question +
+<<HAL Reference#uvw,uvw>> - Hall sensor (trapzeoidal) commutation
+module. +
+<<HAL Reference#vel,vel>> - Velocit Observer +
+<<HAL Reference#vel_int,vel_int>> - Also not sure +
+<<HAL Reference#ypid,ypid>> - YoloPID module. Usable but not used. 
+
+
+== Servoterm
+
+Servoterm (servo terminal) provides an interface which allows editing
+of the drive HAL configuration. It also provides a rolling graphical
+representation of any chosen parameter in the HAL which can be a great
+aid to tuning and motor setup. 
+
+Servoterm is supplied as a Google Chrome Add-in. This might seem
+somewhat odd, but does provide for good cross-platform availability. 
+
+Servoterm can be downloaded from https://github.com/STMBL/Servoterm-app[
+this link].
+Use the green button to download as a ZIP file and then extract on your
+PC (Linux / Mac / PC). Open Google Chrome and click the three-dots icon
+-> more-tools -> extensions.
+
+[width=600, border]
+image::images/Extensions.png[]
+
+Click
+"developer mode" and then "Load Unpacked Extension". Then navigate to
+the downloaded files and select the "Servoterm" folder. 
+You should then be presented with the following, including an option to
+launch the application.
+
+[width=600]
+[.thumb]
+image::images/Extensions2.png[]
+
+To connect to the STMBL you will need a mini-USB B cable.
+
+WARNING:Be sure that the 24V PSU is floating or shares a ground
+reference with the PC.(Maybe even check the voltage between the
+connector and socket before inserting the plug)
+
+You can then click the "connect" button and you should get something
+like the image below. <<Servoterm Connection Problems, what if I can
+not connect>>
+
+image::images/servoterm1.png[]
+
+Taking the buttons from left to right:
+
+* Connect / Disconnect - Should be fairly self-evident
+* Clear - simply clears the screen
+* Reset - Resets the connection. Does not reset the STMBL. To do that
+type the <<Servoterm Commands,`reset`>> command
+* Capture - Allows the output of the graphs to be saved and exported to
+file
+* Jog - when ticked the left-right arrow keys on the keyboard can be
+used to jog the motor. 
+* Trigger - stops the graph plot until the trigger condition is met.
+* Trigger Status Indicator - not a button
+* Edit Config - Brings up a sub-window in which the basic system config
+can be edited. 
+
+Other than the buttons described above the ramainder of servoterm (and
+the STMBL HAL) is controlled by a command-line interface. 
+
+Servoterm uses the up and down arrow keys to scroll through previous
+commands, but there is no tab-completion. 
+
+This is mainly described in the <<HAL (Hardware Abstraction Layer),HAL>>
+section of this document. 
+The graphing display is controlled by the "term0" interface. Typing
+`term0` at the prompt will show output similar to:
+
+image::images/servoterm2.png[]
+
+The first two entries are internal information about the HAL component
+and can be ignored for now.
+The next 8 lines say what internal signal each of the wave plots is
+connected to. In this case wave0 (the black one) is connected to a sim
+signal, in this case the sine wave. (as you might have guessed, typing 
+"sim0" will show you the parameters of the simulated signals.)
+
+To connect wave1 (red) to the sawtooth output (which simulates both
+encoder feedback and a position command for steady rotation) then simply
+type
+`term0.wave1 = sim0.vel`
+Each wave has an associated offset and gain parameter that can be used
+to adjust vertical scale and position. The `term0.send_step` parameter
+functions like the time-base of an oscilloscope. 
+
+=== Servoterm Commands
+
+The servoterm command list can be obtained at the command line by using
+the `help` command. 
+
+* bootloader: enter bootloader
+* reset: reset STMBL
+* confcrc: Shows the CRC checksum of the loaded config. 
+* flashloadconf: load config from flash
+* flashsaveconf: save config to flash
+* loadconf: parse config
+* showconf: show config - pressing the `Edit config` button is better.
+* appendconf: append string to config - also redundant with the config
+editor
+* deleteconf: delete config
+* hal: print HAL stats
+* load: load comp from flash
+* show: show comps in flash
+* list: show comp instances
+* start: start rt system
+* stop: stop rt system
+* fault: trigger fault
+* about: show system infos
+* help: print this
+* link: load config template
+* show_config: show config templates
+
+=== Servoterm Connection Problems
+
+== Flashing Firmware
+
+== Pinouts
+
+=== Command connector wiring:
+
+|===
+|Pin |Colour|Smart Serial |Step/Dir |Quadrature
+
+|1 |Orange Stripe |RX+ |Step+ |A+
+|2 |Orange        |RX- |Step- |A-
+|3 |Green Stripe  |    |Dir-  |B-
+|4 |Blue          |TX+ |      |   
+|5 |Blue Stripe   |TX- |      |   
+|6 |Green         |    |Dir+  |B+ 
+|7 |Brown Stripe  |VCC |VCC   |VCC
+|8 |Brown         |GND |GND   |GND
+|===
+
+=== Feedback connector wiring - encoders etc
+
+|===
+|Pin |Colour |Resolver |Encoder |1Vpp |Mitsubishi |Sanyo-Denki |Yaskawa |Omron
+
+|1 |Orange Stripe |Sin+ |A+  |Sin+ |A+  |    |      |  
+|2 |Orange        |Sin- |A-  |Sin- |A-  |    |      |  
+|3 |Green Stripe  |Cos- |B-  |Cos- |B-  |    |      |  
+|4 |Blue          |Ref- |Z-  |     |    |2   |Blue  |  
+|5 |Blue Stripe   |Ref+ |Z+  |     |    |1   |Brown |5 
+|6 |Green         |Cos+ |B+  |Cos+ |B+  |    |      |4 
+|7 |Brown Stripe  |     |VCC |VCC  |VCC |VCC |Red   |1 
+|8 |Brown         |GND  |GND |GND  |GND |GND |Black |2 
+|===
+
+=== Connector wiring - serial protocols
+
+|===
+|Pin |Colour|RS485 |RS422 |UART |USART |UART HD |USART HD |SPI |SPI HD
+
+|1 |Orange Stripe |    |A   |RX+ |RX+  |       |       |MISO+ |     
+|2 |Orange        |    |B   |RX- |RX-  |       |       |MISO- |     
+|3 |Green Stripe  |    |    |    |CLK+ |       |CLK+   |CLK+  |CLK+ 
+|4 |Blue          |B   |Z   |TX- |TX-  |TX/RX- |TX/RX- |MOSI- |MOSI-
+|5 |Blue Stripe   |A   |Y   |TX+ |TX+  |TX/RX+ |TX/RX+ |MOSI+ |MOSI+
+|6 |Green         |    |    |    |CLK- |       |CLK-   |CLK-  |CLK- 
+|7 |Brown Stripe  |VCC |VCC |VCC |VCC  |VCC    |VCC    |VCC   |VCC  
+|8 |Brown         |GND |GND |GND |GND  |GND    |GND    |GND   |GND  
+|===
+
+
+== Blink Codes
+
+Count the number of blinks of the red LED. Each number indicates a
+different class of faults. 
+
+1. Command error - This will be quite common during setup
+2. Feedback error
+3. Commutation feedback error
+4. Joint feedback error
+5. Position error
+6. Saturation error
+7. HV CRC error
+8. HV timeout error
+9. Overtemperature error
+10. High/Low voltage error (Or no communication with F3 board)
+11. HV fault
+12. Motor overtemperature
+
+
+
+
+