HARmonica
Software Manual
www.elmomc.com
June 2002
Important Notice
This guide is delivered subject to the following conditions and restrictions:
This guide contains proprietary information belonging to Elmo Motion Control Ltd. Such
information is supplied solely for the purpose of assisting users of the HARmonica servo
amplifier.
The text and graphics included in this manual are for the purpose of illustration and reference
only. The specifications on which they are based are subject to change without notice.
Information in this document is subject to change without notice. Corporate and individual
names and data used in examples herein are fictitious unless otherwise noted.
Doc. no.
Elmo Motion Control Ltd.
The Elmo Motion Control warranty for this product covers only the elimination of problems due to manufacturing defects that result in
impaired function. Specifically excluded from this warranty is the elimination of problems caused by abuse, damage, neglect, overloading,
wrongful operation and unauthorized manipulations of the product. This product warranty is for a period of 12 months from the time of
operational startup but no longer than 18 months from shipment from the manufacturing plant. Damage claims that exceed the warranty
obligation – including consequential damages – will be rejected in all cases. If any term or condition in this warranty is at variance or
inconsistent with any provision or condition (whether general or special) contained in or referred to in the Terms of Conditions of Sale
outlined at the back of Elmo’s Standard Acknowledgement form, then the latter shall prevail and be effective.
HARSFEN0602
Copyright
2002
All rights reserved.
Elmo Motion Control Ltd.
64 Gisin St., P.O. Box 463
Petach Tikva
49103
Israel
Tel: +972 3 929-2300
Fax: +972 3 929-2322
Elmo Motion Control Inc.
900(H) River St.
Kennedy Industrial Park
Windsor, CT 06095
USA
Tel: +1 860 683-0095
Fax: +1 860 683-0036
Elmo Motion Control GmbH
Steinbeisstrasse 41
D-78056
Villingen-Schwenningen
Germany
Tel: +49 07720 8577-60
Fax: +49 07720 8577-70
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Table of Contents:
1 ABOUT THIS MANUAL.................................................................................................................................10
1.1 Scope ......................................................................................................................................................................... 10
1.2 Relevant documentation.......................................................................................................................................... 10
1.2.1 Glossary.................................................................................................................................................................10
2 THE HARMONICA .........................................................................................................................................11
2.1 Introduction.............................................................................................................................................................. 11
2.2 Software Organization............................................................................................................................................. 11
2.2.1 The Boot software................................................................................................................................................. 11
2.2.2 The Firmware........................................................................................................................................................ 11
2.2.3 The Personality...................................................................................................................................................... 11
2.3 Related Software...................................................................................................................................................... 12
1
2.4 Units .......................................................................................................................................................................... 12
2.4.1 Position units......................................................................................................................................................... 12
2.4.2 Speed and acceleration units ................................................................................................................................. 13
2.4.3 Current and torque................................................................................................................................................. 13
2.5 Internal Units and Conversions.............................................................................................................................. 13
2.5.1 Current and torque:................................................................................................................................................13
2.5.2 Speed: .................................................................................................................................................................... 14
2.5.3 Electrical angle:..................................................................................................................................................... 14
2.5.4 Power DC voltage ................................................................................................................................................. 14
2.6 Peripherals................................................................................................................................................................ 14
2.6.1 Position decoders...................................................................................................................................................14
2.7 A/D converter........................................................................................................................................................... 15
2.8 Digital inputs ............................................................................................................................................................15
2.9 Digital output............................................................................................................................................................ 15
3 COMMUNICATION WITH THE HOST...........................................................................................................16
3.1 General...................................................................................................................................................................... 16
3.2 RS232 Communications .......................................................................................................................................... 16
3.2.1 RS232 Basics ........................................................................................................................................................ 16
3.2.2 The Echo ............................................................................................................................................................... 17
3.2.3 Background Transmission..................................................................................................................................... 17
3.2.4 Errors and exceptions in RS232............................................................................................................................ 17
3.3 CANopen Communication ...................................................................................................................................... 17
4 THE INTERPRETER LANGUAGE ................................................................................................................18
4.1 The command line.................................................................................................................................................... 19
4.2 Expressions And Operators .................................................................................................................................... 19
4.2.1 Numbers................................................................................................................................................................ 19
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
4.2.2 Mathematical And Logical Operators....................................................................................................................19
4.2.3 General rules for operators....................................................................................................................................20
4.2.4 Operator details......................................................................................................................................................20
4.2.5 Mathematical functions .........................................................................................................................................24
4.2.6 Expressions............................................................................................................................................................25
4.3 Comments .................................................................................................................................................................27
5 THE HARMONICA USER PROGRAMMING LANGUAGE ...........................................................................28
5.1 User Program Organization....................................................................................................................................28
5.2 Common....................................................................................................................................................................29
5.2.1 Line and Expression Termination..........................................................................................................................29
5.2.2 Line Continuation..................................................................................................................................................29
5.2.3 Limitations.............................................................................................................................................................30
5.3 Expressions And Operators.....................................................................................................................................30
5.3.1 Numbers ................................................................................................................................................................30
5.3.2 Mathematical and Logical Operators.....................................................................................................................30
5.3.3 General rules for operators....................................................................................................................................30
5.3.4 Operator details......................................................................................................................................................31
5.3.5 Mathematical functions .........................................................................................................................................31
5.3.6 Expressions............................................................................................................................................................31
2
5.4 Comments .................................................................................................................................................................33
5.5 Program Flow Commands.......................................................................................................................................34
5.5.1 Labels (Entry points).............................................................................................................................................35
5.5.2 For iteration ...........................................................................................................................................................35
5.5.3 While iteration.......................................................................................................................................................36
5.5.4 Until iteration.........................................................................................................................................................37
5.5.5 Wait iteration.........................................................................................................................................................38
5.5.6 IF condition ...........................................................................................................................................................38
5.5.7 Switch selection.....................................................................................................................................................39
5.5.8 Break......................................................................................................................................................................40
5.6 Functions...................................................................................................................................................................40
5.6.1 Function definition ................................................................................................................................................40
5.6.2 Dummy variables...................................................................................................................................................42
5.6.3 Count of output variables....................................................................................................................................... 42
5.6.4 Automatic variables...............................................................................................................................................43
5.6.5 Global variables.....................................................................................................................................................44
5.6.6 Jumps.....................................................................................................................................................................44
5.6.7 Functions and The Call Stack................................................................................................................................45
5.6.8 Killing The Call Stack...........................................................................................................................................47
5.6.9 Automatic subroutines...........................................................................................................................................47
6 PROGRAM DEVELOPMENT AND EXECUTION..........................................................................................51
6.1 Editing a Program....................................................................................................................................................51
6.2 Compilation...............................................................................................................................................................51
6.2.1 Compilation Error List...........................................................................................................................................51
6.3 Downloading and Uploading a Program................................................................................................................59
6.3.1 Binary data.............................................................................................................................................................60
6.3.2 The Assisting Commands For Down/Upload........................................................................................................60
6.3.3 Downloading a Program........................................................................................................................................61
6.3.4 Uploading a Program.............................................................................................................................................62
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
6.4 The program execution............................................................................................................................................ 62
6.4.1 Initiating a Program............................................................................................................................................... 63
6.4.2 Halting and resuming a program........................................................................................................................... 63
6.4.3 Automatic program running with power up.......................................................................................................... 64
6.4.4 Save to Flash......................................................................................................................................................... 64
6.5 Debugging.................................................................................................................................................................64
6.5.1 Running, breaking, and resuming..........................................................................................................................64
6.5.2 DB command ........................................................................................................................................................ 64
6.5.3 Machine status....................................................................................................................................................... 65
6.5.4 Program status....................................................................................................................................................... 65
6.5.5 Setting and clearing break points .......................................................................................................................... 66
6.5.6 Continuation of the program................................................................................................................................. 66
6.5.7 Single step............................................................................................................................................................. 66
6.5.8 Getting stack entries.............................................................................................................................................. 68
6.5.9 Setting stack.......................................................................................................................................................... 68
6.5.10 Getting call stack.............................................................................................................................................. 68
6.5.11 View of global variables................................................................................................................................... 69
6.5.12 View of local variables..................................................................................................................................... 69
7 THE VIRTUAL MACHINES............................................................................................................................71
7.1.1 Introduction Alla please complete where necessary.............................................................................................. 71
3
7.2 Virtual Machine registers........................................................................................................................................ 71
7.3 Call Stack During Function Call ............................................................................................................................ 71
7.4 Data types ................................................................................................................................................................. 72
7.5 Op code structure and addressing modes .............................................................................................................. 73
7.6 Short reference......................................................................................................................................................... 73
7.7 Alphabetic reference................................................................................................................................................ 75
7.7.1 ADD - ADDITION ............................................................................................................................................... 75
7.7.2 AND – Bitwise AND Operator............................................................................................................................. 75
7.7.3 CMP – Compare.................................................................................................................................................... 76
7.7.4 DIV – Divide......................................................................................................................................................... 76
7.7.5 EOL – End Of Line............................................................................................................................................... 77
7.7.6 FORITR – FOR Loop Iteration............................................................................................................................. 77
7.7.7 FREE_VAC - Free Virtual Machine.................................................................................................................... 78
7.7.8 F_OR – Bitwise OR Operator............................................................................................................................... 78
7.7.9 GETINDEX........................................................................................................................................................... 78
7.7.10 GET_COMM – Get Command ........................................................................................................................ 79
7.7.11 JMP – Jump...................................................................................................................................................... 79
7.7.12 JMP_EOL – Jump ............................................................................................................................................ 80
7.7.13 JMP_LABEL – Jump to the label..................................................................................................................... 80
7.7.14 JNZ – Jump Not Zero....................................................................................................................................... 81
7.7.15 JNZ_EOL – Jump Not Zero ............................................................................................................................. 81
7.7.16 JZ – Jump If Zero............................................................................................................................................. 82
7.7.17 JZ_EOL – Jump If Zero....................................................................................................................................82
7.7.18 LINK ................................................................................................................................................................ 82
7.7.19 MLT – Multiply................................................................................................................................................ 83
7.7.20 MOV – Assignment Operator (=)..................................................................................................................... 83
7.7.21 NOT – Bitwise NOT Operator ......................................................................................................................... 84
7.7.22 REM – Reminder.............................................................................................................................................. 84
7.7.23 RSLTA – Relational Operator (>).................................................................................................................... 85
7.7.24 RSLTAE – Relational Operator (>=) ............................................................................................................... 85
7.7.25 RSLTAND – Logical AND Operator (&&)..................................................................................................... 86
7.7.26 RSLTB – Relational Operator (<).................................................................................................................... 86
7.7.27 RSLTBE – Relational Operator (<=)................................................................................................................86
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
7.7.28 RSLTE – Relational Operator (==)...................................................................................................................87
7.7.29 RSLTNE – Relational Operator (!=).................................................................................................................87
7.7.30 RSLTOR – Logical OR Operator ( || )..............................................................................................................88
7.7.31 SET_COMM – Set Command..........................................................................................................................88
7.7.32 SETINDEX.......................................................................................................................................................89
7.7.33 SHR – Shift Right.............................................................................................................................................89
7.7.34 SHL – Shift Left ...............................................................................................................................................89
7.7.35 SPADD .............................................................................................................................................................90
7.7.36 SUB - SUBTRACT ..........................................................................................................................................90
7.7.37 SYSSUBJ – Jump To System Subroutine.........................................................................................................91
7.7.38 UNARY_NOT - Logical NOT Operator (!) .....................................................................................................91
7.7.39 USRSUBJ – jump To User Subroutine.............................................................................................................92
7.7.40 USRSUBRT – Return from user subroutine.....................................................................................................92
7.7.41 XOR – Bitwise XOR Operator .........................................................................................................................93
8 THE RECORDER ...........................................................................................................................................94
8.1 Recorder sequencing: Programming, launching, and uploading data. ...............................................................94
8.2 Signal mapping .........................................................................................................................................................95
8.3 Defining the set of recorded signals........................................................................................................................96
4
8.4 Programming the length and the resolution ...................................................................................... ....................96
8.5 Trigger events and timing........................................................................................................................................97
8.6 Launching the recorder .........................................................................................................................................100
8.7 Uploading recorded data .......................................................................................................................................100
9 COMMUTATION...........................................................................................................................................103
9.1 General....................................................................................................................................................................103
9.1.1 Brush DC motors.................................................................................................................................................103
9.1.2 The Stepper Commutation Policy........................................................................................................................103
9.1.3 The BLDC commutation policy ..........................................................................................................................104
9.2 Mechanical and electrical motion Figures are missing .......................................................................................104
9.3 Commutation sensors.............................................................................................................................................105
9.3.1 Rotor Magnetic field sensors...............................................................................................................................105
9.3.2 Shaft Angle Sensors.............................................................................................................................................106
9.3.3 Combination of direct magnetic field sensors and shaft angle sensor .................................................................106
9.3.4 Parameterization of the commutation and the commutation sensors...................................................................107
9.4 Commutation search..............................................................................................................................................109
9.4.1 General ................................................................................................................................................................109
9.4.2 Selecting the parameters......................................................................................................................................109
9.4.3 Method limitation................................................................................................................................................110
9.4.4 Protections...........................................................................................................................................................110
9.4.5 Parameters related to starting the motor with no digital Hall sensors..................................................................111
9.5 Continuous Vs. Six-Steps commutation................................................................................................................111
9.5.1 Six-step commutation..........................................................................................................................................112
9.5.2 Continuous commutation.....................................................................................................................................112
9.6 Winding shapes .......................................................................................................................................................113
9.6.1 Loading the commutation table...........................................................................................................................114
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
10 THE CURRENT CONTROLLER..................................................................................................................115
10.1.1 Current limiting.............................................................................................................................................. 116
10.1.2 The torque command filter............................................................................................................................. 118
10.1.3 The PI current controller.................................................................................................................................120
10.2 Current amplifier protections............................................................................................................................... 121
11 UNIT MODES ...............................................................................................................................................123
11.1 Torque control: Unit mode 1................................................................................................................................. 123
11.2 Speed mode: Unit mode 2...................................................................................................................................... 124
11.2.1 The software speed command ........................................................................................................................ 124
11.2.2 The auxiliary speed command........................................................................................................................ 126
11.2.3 Stop management........................................................................................................................................... 127
11.3 The stepper mode: Unit mode 3............................................................................................................................ 128
11.4 The Dual feedback mode: UM=4.......................................................................................................................... 129
11.5 The single feedback mode: UM=5 ........................................................................................................................ 131
5
12 THE POSITION REFERENCE GENERATOR.............................................................................................132
12.1 The software reference generator......................................................................................................................... 132
12.1.1 Switching Between Motion Modes ................................................................................................................ 132
12.1.2 Comparison of the PT and the PVT interpolated modes................................................................................ 133
12.1.3 The Idle Mode and Motion Status.................................................................................................................. 133
12.1.4 Point-To-Point (PTP)...................................................................................................................................... 134
12.1.5 Jogging ........................................................................................................................................................... 138
12.1.6 PVT: Position-Velocity-Time interpolated motion ....................................................................................... 140
12.1.7 PT Motion.......................................................................................................................................................153
12.2 The External Position Reference Generator........................................................................................................ 159
12.2.1 ECAM ............................................................................................................................................................ 162
12.2.2 Dividing ECAM table into several logical portions ....................................................................................... 165
12.2.3 On the fly ECAM programming using CAN.................................................................................................. 166
12.2.4 Initializing the external reference parameters................................................................................................. 167
12.3 The Stop management........................................................................................................................................... 168
12.3.1 General description......................................................................................................................................... 168
12.3.2 Stop Manager Internals................................................................................................................................... 169
13 SENSORS, I/O, AND EVENTS....................................................................................................................172
13.1 Modulo counting .................................................................................................................................................... 172
13.1.1 Modulo Counting............................................................................................................................................ 172
13.2 Digital Inputs.......................................................................................................................................................... 173
13.3 Digital Outputs....................................................................................................................................................... 173
13.4 Events, and response methods ................................................................................................... ........................... 174
13.4.1 Manual inquiry ............................................................................................................................................... 174
13.4.2 Periodical Inqu iry........................................................................................................................................... 174
13.4.3 Automatic routines ......................................................................................................................................... 175
13.4.4 Real time – Motion management, Homing, Capture, and Flag...................................................................... 175
13.5 Homing and Capture............................................................................................................................................. 175
13.5.1 What Is Homing?............................................................................................................................................ 175
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
13.5.2 Homing Programming ....................................................................................................................................176
13.5.3 Homing the auxiliary encoder.........................................................................................................................176
13.5.4 On the fly position counter updates ................................................................................................................177
13.5.5 A homing with home switch and index example............................................................................................177
13.5.6 Capturing ........................................................................................................................................................180
14 LIMITS, PROTECTIONS, FAULTS, AND DIAGNOSIS...............................................................................181
14.1 Current limiting......................................................................................................................................................182
14.2 Speed Protection.....................................................................................................................................................183
14.3 Position Protection .................................................................................................................................................184
14.4 Enable switch..........................................................................................................................................................185
14.5 Limit switches.........................................................................................................................................................186
14.6 Connecting an external brake ...............................................................................................................................186
14.7 When the motor fails to start.................................................................................................................................187
6
14.8 Motion faults...........................................................................................................................................................187
14.9 Diagnosis .................................................................................................................................................................189
14.9.1 Monitoring motion faults................................................................................................................................189
14.9.2 Inconsistent setup data....................................................................................................................................189
14.9.3 Device failures, and the CPU dump................................................................................................................190
14.10 Sensor faults............................................................................................................................................................190
14.10.1 The motor cannot move..................................................................................................................................190
14.11 Commutation is lost................................................................................................................................................191
14.11.1 General............................................................................................................................................................191
14.11.2 Reasons and effect of incorrect commutation .................................................................................................191
14.11.3 Detection of Commutation Feedback Fault....................................................................................................192
15 THE CONTROLLER.....................................................................................................................................193
15.1 General ....................................................................................................................................................................193
15.2 Speed Control .........................................................................................................................................................194
15.2.1 Block diagram.................................................................................................................................................194
15.2.2 The Parameters of the Speed Controller.........................................................................................................195
15.3 The Position Controller..........................................................................................................................................196
15.3.1 Block Diagram................................................................................................................................................196
15.3.2 The Parameters of the Position Controller......................................................................................................197
15.4 The High Order Filter............................................................................................................................................198
15.4.1 Block Types....................................................................................................................................................198
15.4.2 User Interface..................................................................................................................................................200
15.5 The Gain-Sche duling Algorithm...........................................................................................................................201
15.6 Automatic Controller Gain-Scheduling................................................................................................................202
16 APPENDIX A: THE HARMONICA FLASH MEMORY ORGANIZATION....................................................204
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
16.1 Main partitions....................................................................................................................................................... 204
16.2 The firmware partition..........................................................................................................................................204
16.2.1 Table of Contents (TOC)................................................................................................................................ 204
16.2.2 Contents of Text1........................................................................................................................................... 205
16.2.3 Contents of Text2........................................................................................................................................... 205
16.2.4 Contents of Text3........................................................................................................................................... 205
16.2.5 Contents of Text4-Text7................................................................................................................................. 206
16.2.6 Contents of Text8........................................................................................................................................... 207
16.2.7 Contents of Text9........................................................................................................................................... 207
16.2.8 Contents of Text10......................................................................................................................................... 209
16.2.9 Contents of Binary1........................................................................................................................................ 209
16.2.10 Contents of Binary2........................................................................................................................................ 209
16.2.11 Contents of Binary3........................................................................................................................................ 209
16.3 Parameters Partition..............................................................................................................................................209
16.4 Factory Code Partition.......................................................................................................................................... 209
16.5 User Code partition................................................................................................................................................ 209
16.5.1 The TOC......................................................................................................................................................... 210
16.5.2 The Compilation Done Flag ........................................................................................................................... 210
16.5.3 The Virtual Machine Code Segment .............................................................................................................. 211
16.5.4 The Text Backup & Compiler data segment .................................................................................................. 211
16.5.5 The Function Symbol Table........................................................................................................................... 211
16.5.6 The Variable Symbol Table............................................................................................................................ 212
16.5.7 The Automatic Routines Table....................................................................................................................... 212
7
17 APPENDIX B: HARMONICA INTERNALS .................................................................................................213
17.1 Software Structure.................................................................................................................................................213
17.1.1 The Initialization block................................................................................................................................... 213
17.1.2 The periodic Interrupt..................................................................................................................................... 213
17.1.3 The Idle Loop................................................................................................................................................. 214
18 APPENDIX C: CONVERTING CLARINET/SAXOPHONE PROGRAMS TO THE HARMONICA
LANGUAGE..........................................................................................................................................................216
18.1 The Converter ........................................................................................................................................................ 216
18.2 The Converter Call ................................................................................................................................................ 216
18.3 The Algorithm ........................................................................................................................................................ 216
18.4 The Conversion Process......................................................................................................................................... 216
18.5 Examples................................................................................................................................................................. 217
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
List of Tables:
Table 2-1: Analog sampled signals.........................................................................................................................15
Table 3-1 – RS232 Rx Item Description.................................................................................................................16
Table 3-2 – RS232 Tx Item Description.................................................................................................................17
Table 4-1 – Mathematical and Logical Operators...................................................................................................20
Table 5-1 – Automatic subroutines and their priority.............................................................................................49
Table 7-1 – Harmonica op codes...........................................................................................................................75
Table 8-1: Commands relevant to the recorder.......................................................................................................94
Table 8-2: Default mapping of recorded signals.....................................................................................................95
Table 8-3: Some additional recorded signals...........................................................................................................96
Table 8-4: RR command options...........................................................................................................................100
Table 8-5: RR reports............................................................................................................................................100
Table 8-6: SR recorder status reports....................................................................................................................100
Table 8-7:Parameters for uploading recorded data................................................................................................100
Table 8-8: BH – record structure...........................................................................................................................102
Table 9-1: Hall sensor values................................................................................................................................105
Table 9-2: Six-Steps commutation........................................................................................................................112
Table 10-1: Bandwidth selections for bus voltage filter........................................................................................121
Table 12-1: Software motion mode commands.....................................................................................................132
Table 12-2 – Tabulated Motion Difference...........................................................................................................133
Table 12-3 – Tabulated Feature Preference...........................................................................................................133
Table 12-4: Motion status indications...................................................................................................................134
Table 12-5 – Parameter of PTP Motion.................................................................................................................135
Table 12-6 – PVT Table........................................................................................................................................144
Table 12-7 – PVT Motion Parameters...................................................................................................................145
Table 12-8 – PVT Related Parameters..................................................................................................................151
Table 12-9 – PVT CAN Emergency Messages.....................................................................................................152
Table 12-10 – PT Motion Parameters....................................................................................................................155
Table 12-11 – PT Related Parameters...................................................................................................................159
Table 12-12 – PT CAN Emergency Messages......................................................................................................159
Table 12-13 – ECAM Related Command.............................................................................................................162
Table 13-1: Commands relevant to modulo counting...........................................................................................172
Table 14-1: Commands relevant to limits, protection, and diagnosis...................................................................182
Table 14-2: Cases where feedback limits do not apply.........................................................................................184
Table 14-3 - CD Reported Elements.....................................................................................................................190
Table 15-1 – Unit Mode Values and Definitions...................................................................................................193
Table 15-2 – List of all control parameters...........................................................................................................194
Table 15-3: Programming sets of controller parameters for gain schedulilng ......................................................202
Table 15-4 – Automatic Gain Scheduling Process................................................................................................203
Table 15-5 – Gain scheduling automatic indexing parameter...............................................................................203
8
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
List of Figures:
Figure 1 - Slope and window trigger types.............................................................................................................98
Figure 2 – Pre trigger delay.....................................................................................................................................99
Figure 3: Two phased linear motor.......................................................................................................................104
Figure 4: Three phased line ar motor.....................................................................................................................104
Figure 5: Three phase rotary motor.......................................................................................................................104
Figure 6: Digital Hall sens o rs readout...................................................................................................................106
Figure 7: Loss of torque due to commutation miss...............................................................................................112
Figure 8: Winding shape funct ion for a Trapeze motor.......................................................................................113
Figure 9: Winding shape function for sinusoidal motor........................................................................................114
Figure 10: Current controller structure..................................................................................................................115
Figure 11: Peak/Continuous current limit selection..............................................................................................117
Figure 12: Time constant selection (Small signal) for the torque inpu t filter.......................................................119
Figure 13: Rate limiting for the torque input filter................................................................................................120
Figure 14: Current PI controller............................................................................................................................120
Figure 15: Unit mode 1 (Torque) structure...........................................................................................................123
Figure 16: Unit mode 2 (Speed) structure.............................................................................................................124
Figure 17 – Speed Profiling using JV, AC and DC ..............................................................................................125
Figure 18 – Speed command for different smooth Factor.....................................................................................126
Figure 19: Auxiliary spe ed com m and generati on.................................................................................................127
Figure 20: Speed mode Stop Manager..................................................................................................................127
Figure 21: Stepper mode (UM=3).........................................................................................................................129
Figure 22: Dual feedback mode (UM=4)..............................................................................................................130
Figure 23: Dual feedback mode (UM=5)..............................................................................................................131
Figure 24 – PTP Decisions Flow Chart.................................................................................................................137
Figure 25 – Jog Decisions Flow Chart..................................................................................................................138
Figure 26 – PVT Decisions Flow Chart................................................................................................................146
Figure 27 – PVT Auto Increment Mode Flow Chart............................................................................................149
Figure 28 – PT Decisions Flow Chart...................................................................................................................155
Figure 29 – PT Auto Increment Mode Flow Chart...............................................................................................157
Figure 30: External position reference generator..................................................................................................160
Figure 31: Print On A Moving Box Application...................................................................................................168
Figure 32: Stop Manager Block Manager.............................................................................................................169
Figure 33: Position output of the stop manager....................................................................................................171
Figure 34: Speed output of the Stop Manager.......................................................................................................171
Figure 35 – Switches location...............................................................................................................................178
Figure 36: Speed command and feedback limits..................................................................................................184
Figure 37: Position command and feedback limits...............................................................................................185
Figure 38: Brake output connection......................................................................................................................186
Figure 39: Normal Brake Activation Timing........................................................................................................187
Figure 40 – A Block Diagram of the Speed Controller.........................................................................................195
Figure 41 – Block Diagram of The Dual Loop Controller....................................................................................197
Figure 42: Idle loop...............................................................................................................................................215
9
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
1 About This Manual
1.1 Scope
This specification presents relevant data for understanding and using the Harmonica
software.
The Software Specification complements the Command Reference Manual. The Command
Reference Manual lists each single command with all its options. The Software
Specification Manual is designed to give wider view of the Harmonica system. The topics
are covered functionally, with reference to many commands.
1.2 Relevant documentation
Document Comments
The Harmonica Command Reference
Manual
The Harmonica CAN Manual A Complementary document. The CAN
The Harmonica User Manual A Complementary document. This document
The Composer Manual This manual explains the Composer IDE and
A complementary document. The Command
Reference Manual lists the system variables
and interpreter commands of the Harmonica.
Manual explains the CAN communication
objects of the Harmonica, and their usage.
describes how to select the right Harmonica
model, how to install it, and how to perform
initial setup
how to best use it with the Harmonica.
10
1.2.1 Glossary
The following abbreviations and terms are used in this document:
ALU Arithmetic Logic Unit, the part of the CPU that makes math and address
ICD Interface control document. A definition for the external world relations of a
CSCI Computer Software Configuration Item. A stand alone program that as long as it
CSU Computer Software Unit. A functional block in the software.
DSP Digital Signal Processor.
EDS The list of CAN object supported by a device, in a standard form suitable for
ID Direct current. The current component that generate magnetic field in parallel to the
IDE Integrated development environment
IQ Quadrature current. The current component that generate magnetic field
PDO Process Data Object. A CAN message type. A PDO avoids the need to allocate data
PPR Pulse Per Revolution
calculations.
product. For software, the ICD defines external I/O relations.
conforms its ICD, may be freely maintained.
standard configuration software.
fixed magnet of the rotor
perpendicular to the fixed magnet of the rotor
payload for object addressing by a pre-agreement (called PDO mapping) about the
message contents.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
2 The Harmonica
2.1 Introduction
The Harmonica a sophisticated and capable network-oriented single-axis amplifier, with:
- State of the art control algorithms, including high order filters and gain
scheduling
- State of the art reference generation algorithm, including absolute timed
interpolated motion, auxiliary signal following, and ECAM.
- Synchronization capability for network operation
- Conformance to CANopen standards
- User friendly programming
- Advanced analyzing tool for setup behavior
- Built in auto-tuning facilities
- Built in database maintenance tools.
- Built in firmware maintenance tools.
All these are implemented in the extremely small environment of the DSP.
11
2.2 Software Organization
The DSP software is divided into three parts.
The first part is the boot software. The boot software is permanently burnt into the code
flash internal to the DSP, and cannot be upgraded during product life. The boot software
includes some data that helps the firmware identify the exact amplifier model it is operating.
The data includes the maximal motor phase current, the nominal bus voltage, the hardware
of the communication sensors and I/O interface, and the grade of the amplifier (basic or with
extended capabilities).
The second part is the operational software (firmware). The firmware may be updated at
the user site if some upgrading or modifications are required.
The third part is a supportive database that must be loaded to the serial flash. This
supportive part provides a file system for personality description, storage of application
database, and factory or user provided programs.
2.2.1 The Boot software
The Boot software has the following functions:
- Initialize some of the registers of the DSP
- Test code validity automatically. If code validation fails, pass automatically to
the "Download Firmware" mode.
- Degenerated RS232 communication handling and interpreter, only in the level
required for firmware downloading functions.
- Support firmware downloads into the on-chip flash memory.
- Pass control to start of firmware.
2.2.2 The Firmw are
The firmware implements all the other software functions, as described in this manual and in
the Command Reference manual.
The firmware will pass control to the boot software when a DF command initiates a
firmware version upgrade. At the end of the firmware downloading process, the Harmonica
reboots.
2.2.3 The Personality
Elmo HARmonica Software Manual
For rotary motors, CA[18] is the number of sensor counts per one full
HARSFEN0602
P R E L I M I N A R Y D R A F T
The personality data is loaded to the serial flash memory. The personality data includes a
file allocation table and several files. The personality files include data about the Harmonica.
A partial list is:
List of supported command
List of error code
CAN EDS
All these data items enable an IDE to deal with the Harmonica. The File Allocation table
reserves place for storage of application parameters and of user programs. The personality
data is burnt into the serial flash using the firmware software.
The firmware can boot without personality data, but it will not become fully functional
before the personality data is programmed in place.
Full explanations of the personality data are given in the chapter “Appendix A: The
Harmonica Flash Memory Organization”.
2.3 Related Software
The Harmonica requires supporting software for setup, tuning, programming, and
performance assessment. The support software is called “Composer”. It runs on a PC
computer, under Windows.
The Composer includes the following functions (among many others):
•
Terminal for direct user interface by RS232 or by CAN
•
A recorder with advanced scope controls. You can observe up to 8 signals
simultaneously, triggered by a selection of events.
•
Setup and tuning tools:
•
Menus for entering basic application data and limits
•
Tools for associating functions to I/O connector pins
•
Automatic tuning of current controller
•
Automatic tuning for commutation
•
Manual and automatic Speed controller tuning
•
Manual and automatic Position controller tuning
•
Application database maintenance
•
Save and load application database
•
Edit application parameters, with help
•
Advanced IDE for user program development:
•
Editor
•
Compiler
•
Downloading and uploading of user programs
•
Debugger, with:
•
Various break point and stepping options
•
Watches for local and global variables
•
Call stack watch
The Composer software reads the personality data from the Harmonica, and can therefore
adapt to the specific amplifier model you bought.
12
2.4 Units
This section describes how the Harmonica measures time, position, speed, voltage, and
current.
2.4.1 Position units
The Harmonica refers to position by sensor counts. The sensor counts may be related to
physical units using the following commands:
Command Description
CA[18]
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
mechanical revolution.
CA[23] For linear motors, CA[23] stores the number of counts per user unit (Meter, or
any other unit the user may select). CA[23] is stored only for convenience – the
Harmonica software does not use this number for any internal calculation.
For rotary motors, set CA[23]=0.
YA[1],YA[3] YA[1] is the auxiliary feedback resolution, counts/physical unit. YA[3] sets
what a physical unit is: Revolution, Meter, or other.
YA[1] and YA[3] are stored only for convenience – the Harmonica software
does not use these numbers for any internal calculation.
2.4.2 Speed and acceleration units
The speed units are counts/sec, and the acceleration units are counts/sec2. The speed units
may be related to physical units by converting the counts to revolutions, Meters, etc, as
explained in the section "Position units" above.
2.4.3 Current and torque
Currents are measured in Amperes. That is not so simple as it sounds, since there is no
single accepted method to specify the current of three-phased motors.
For sinusoidal motors, RMS phase current normally specifies the motor current. The RMS is
taken over a mechanical revo lution; so that the phase currents are the "Motor current" only if
the motor revolves with constant speed.
For trapeze-wound motors, the conventional six-steps drive leaves one motor phase open
circuited, and only one current flows through the two driven motor phases. This driven
phases current specifies the "Motor current". For trapeze-wound motor running six-step
commutation continuously at 1Amp, the RMS current is 0.92Amp.
The Harmonica has one motor current definition, although it can run equally well sinusoidal,
Trapezoidal, or free form motor windings.
We defined the motor current as the maximum winding current in a mechanical revolution.
This definition is consistent with the traditional current definition for six-step motors and it
readily extend to other winding forms.
The user of sinusoidal motors must multiply the motor current reported by the Harmonica by
the factor of 0.71 to obtain the RMS phase current.
13
2.5 Internal Units and Conversions
In order to optimize the use of its CPU, the Harmonica works inside with local units for
time, for current, for DC bus voltage, and for electrical angle.
•
The user normally thinks of time in terms of seconds. Most of the control algorithms view time
by counting controller sampling-times.
•
The user thinks of currents in terms of Amperes. The Harmonica thinks internally in the terms of
A/D bits.
•
The user may think of electrical angles in terms of degrees or radians. The Harmonica divides
the electrical cycle to 1024.
Normally the internal representation of time and currents is transparent to the user. For
example, the user demands motor current in Amperes, and accepts motor current reports in
Amperes as well. The Harmonica does the translation. The following situations, however,
require the user to consider the internal data representation.
•
Uploading data from the real time recorder - Refer "The Recorder" Chapter.
•
Interpreting CAN mapped synchronous PDO's
•
Specifying motions in the micro stepping mode.
Some user interface commands retrieve the conversion factors for user convenience.
2.5.1 Current and torque:
Elmo HARmonica Software Manual
Hz
5000
HARSFEN0602
P R E L I M I N A R Y D R A F T
The internal representation of phase currents is by A/D bits.
Torque commands, and the active and the reactive parts of the current have another
representation, since the coordinate transformations from phase current to torque introduce
scaling.
The relation between internal phase currents, internal torque, and Amperes is given by the
following commands:
Command Description
MC The full current range of the amplifier.
The amplifier represents MC Amperes by 14000 bits internally.
(The maximum A/D reading is 16384 and some spare is left for overshoots and
over-current detection)
WS[22] Torque command multiplier.
Internal torque command = WS[22]×DV[1].
WS[5] Phase current multiplier
Internal phase current = WS[5]×Phase Current[Amp]
2.5.2 Speed:
Speeds are represented internally by the units of counts/(216 speed controller sampling
times).
For example, if the sampling time of the speed controller is 200usec (5000Hz sampling
16
21000
frequency), then 1000 counts/sec will be represented internally as
⋅
13107
=
.
14
The relation between speeds and internal commands is given by the following commands
Command Description
TS Sampling time of the current controller. The sampling time of the sped
WS[53] Conversion from internal units to counts/sec
2.5.3 Electrical angle:
The electrical angle is measured by 1024 counts per electrical revolution.
Think of a motor with 3 pole pairs. To rotate this motor a full mechanical revolution in the
stepper mode (UM=3) you have to specify the m ov em ent of (3×1024)=3072 position counts.
2.5.4 Power DC voltage
Power DC voltage is represented internally in A/D units.
The relation between the internal representation and the bus voltage is given by:
Command Description
WS[54] Conversion from internal units to Volts.
2.6 Peripherals
controller is 4×TS.
Speed (counts/sec) = WS[53]×Speed (Internal representation)
Power DC voltage = WS[54]×Power DC voltage (Internal representation)
This section summarizes the set of Harmonica peripherals.
2.6.1 Position decoders
There are two position decoders, termed main and auxiliary. The main and the auxiliary
decoders are similar. Both decoders are timed (through the timer sets A and B) for accurate
speed information.
A position decoder measures quadrature or Pulse/Direction. The maximum counting rate of
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
a decoder is 20mHz, without input filter.
If input filter is applied, the maximum pulse rate is reduced, as explained at the EF[N]
command in the Command Reference Manual.
The encoder input is not protected. There is no hardware to identify illegal transitions.
Exceeding the maximal pulse rate will cause loss of counts that cannot be detected.
2.7 A/D converter
The A/D samples the following:
Signal Description
Ia,Ib,Ic The three phase currents, sampled simultaneously
Ain,ref The analog input and the reference voltage are sampled simultaneously to
form a differential measurement
Bus voltage The bus voltage is sampled to correct the current loop gain.
Table 2-1: Analog sampled signals
The resolution of all the measurements is 12bit, and in practice the last bit is noisy.
The motor currents are measured offset-free, because of a special measurement mechanism.
The analog inputs cannot avoid an offset, due to electronic inaccuracies in the Harmonica
circuits. This offset can be corrected using the AS[1] parameter, to the resolution of about
5mv.
The ability to correct offsets by AS[1] is limited to the resolution of 5mv, and about 10mv in
practice. This means that, for example, if AG[2]=10000, the offset correction quality to
speed analog reference will be limited to about 100count/sec.
15
2.8 Digital inputs
The Harmonica has six digital input connector pins. All the input pins are routed to a digital
input port. In addition two pins (5 and 6) are routed to high speed capturing input for main
and auxiliary homing. You can associate special functions to digital input pins, like Enable,
Stop, RLS, and FLS – refer the IL command in the Command Reference Manual.
The digital input response time is limited by the speed of the optical couplers, and also by
the input filters.
The encoder index and home input are filtered similarly to the position decoders. The timing
of the position decoder filters is explained in the EF[N] documentation in the command
reference.
The other digital inputs are filtered in software only. The timing of software filtering is
explained in the IF[N] documentation in the command reference.
The use of the digital inputs is detailed in the chapter on Sensors, I/O, and Events.
2.9 Digital output
The Harmonica has two digital output connector pins.
These two pins can be used for non-committed digital outputs, or programmed by the OL
command for special functions, like activating external brakes.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
3 Communication With the Host
3.1 General
3.2 RS232 Communications
The Harmonica can communicate by RS232 with baud rates up to 115200baud/sec.
The maximum baud rate depends in the sampling time. The baud rate of 115200baud/sec
works only when TS equals or is less than 70. The communication rate of 57600 baud/sec
works with all sampling time options.
Please refer to PP[] command in the Command Reference Manual.
3.2.1 RS232 Basics
The RS232 method can only serve to communicate a host to a single amplifier. The RS232 lines are full
duplex – they can carry bidirectional communications. This means that the host can transmit to the amplifier
whenever it finds it right, without considering the state of the amplifier.
The RS232 communication consists of ASCII printable characters only, with some exceptions:
•
The characters 0xD (carriage return).
•
Some non-printable characters that are used as error codes. Please refer to EC command in the
Command Reference.
The basic syntax for RS232 commands may be an assignment,
<Command mnemonic>{[<index>]}{<Equal sign><Value>}<Terminator>
Or a free evaluation:
<Value><Terminator>
Where
Item Description
Command mnemonic Two letters (case insensitive) assigned to a command. Please see the
Command Reference manual for a complete list of command
mnemonics.
Index The index, if the mnemonic refers to a vector parameter or command.
Equal sign The ‘=’ character (Optional, if the command assigns a value to a
parameter)
Value Parameter value (Optional, if the command assigns a value to a
parameter)
The parameter value may be any legitimate arithmetic or functional
expression, as explained later in this section.
Terminator
<CR>
1
or ‘;’.
16
Table 3-1 – RS232 Rx Item Description
An assignment evaluates an expression and stores the result in a variable.
A free evaluation evaluates an expression and sends the result to the terminal.
Typical examples are:
MO<CR>
Asks the amplifier to report the value of the variable MO.
MO=1<CR>
1
<CR> is a carriage return, which is the character 0xd (13 decimal).
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Sets the value of 1 to the MO variable.
CA[2]=1;
Sets the value of the CA[2] variable. CA[N] denotes a vector of parameters that can be accessed by their
index.
The free evaluation
(5+sin(PX))*sqrt(abs(VX))
Returns a numerical value to the terminal.
More detail about text interpreting is given in the chapter "The Interpreter Language".
The amplifier responds to the host communicated commands. It never initiates an unasked-for message to
the host.
The syntax of the amplifier answers is
{<Value>}{<Error code>}<Terminator>
Where
Item Description
Value Parameter value (Optional, if the command asks to report parameter)
Error code A binary number that may be interpreted according to the error code tables –
please refer the EC Command in the Command Reference Manual.
Terminator ‘;’ if the host command has been successfully executed, else ‘;?’
17
Table 3-2 – RS232 Tx Item Description
3.2.2 The Echo
When using RS232 each character that is received by the amplifier is echoed back to the host. The echo is
immediate, per each received character.
3.2.3 Background Transmission
When the host enters the BH=n command to the amplifier, the amplifier uploads the recorder data to the
host. The uploading process may take few seconds. At the time the amplifier uploads records to its host, it is
still listening to the host for new commands.
Consider the command sequence
BH=1;MO=0<CR>
The amplifier will start to transmit the recorder data immediately. Few milliseconds later, while the recorder
data is still transmitting, the amplifier will execute the MO=0 command. The amplifier will store the
response message to the MO=0 command, in order to transmit it later, immediately after the records upload
terminates.
Note:
If the host does not know the communication parameters, it may transmit a series of terminators and try
several baud rates, until it can receive a matching sequence of echoes.
3.2.4 Errors and exceptions in RS232
If an error is intercepted (Overrun, noise, parity, framing), then the entire message including this
error is discarded, and answered by the “communication error” code response.
Although the communication is defined as 8 bits per character, only the byte values 0-127 are used.
The characters 127-255 are treated as UART errors.
Empty strings with terminators are echoed back, but otherwise ignored.
3.3 CANopen Communication
A detailed description of CANopen communications is out of the scope of this manual.
Please refer the CANopen Manual.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
4 The Interpret er Language
The amplifier has a language that enables the user to communicate with the Amplifier. Using this language,
the user can
•
Setup the Amplifier
•
Command the Amplifier what to do
•
Inquire the Amplifier status
There are two methods for communicating with the Amplifier.
The first of them is to use the communication interfaces, either the RS232 or the CANopen
interface, to pass commands to the Amplifier, and accept the Amplifier immediate response.
This method requires on line communication and close cooperation between the Amplifier
and its host.
The other method is to write a program in the Amplifier language and to store it in the
Amplifier. The Amplifier can run the program with minimal or no host assistance.
The physics and the standards of the RS232, and CANopen communication methods imply
differences in the command syntax used by each method.
This section describes the Amplifier language in the basic “RS232” or CAN “OS” syntax.
The CANopen communication method can access simple numeric interpreter get and set
commands very efficiently. The CAN binary interpreter uses PDO objects to issue
interpreter commands and to collect the response.
This is the most economical way minimizes both the communication load and the Amplifier
CPU load.
The CAN OS (command prompt) method can be used to access the entire set of interpreter
services, including those inaccessible by the binary CAN interpreter, using a text format.
The CANopen communication method is a broad topic and is beyond the scope of this
manual. Please refer the CANopen Communication Manual.
Programs use the interpreter syntax, with extension that are necessary to support program
flow instructions and in line documentation.
The full set of the Amplifier commands is documented in the Amplifier Command
Reference Manual.
18
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
4.1 The command line
The Interpreter evaluates input strings, called “expressions”. An expression is a sequence of
characters, terminated by a semicolon ‘;’, a line feed, or a carriage return.
A command line may include the “Comment marker” – two consecutive asterisks. All the text from
the comment marker to the next line feed or carriage return is ignored.
The maximal expression length is 512 symbols.
The comment marker feature enables the preparation of documented batch files, to be later sent
directly to the amplifier.
Example:
a = 3 ; b = 2 ; c = a + b ** Ignore this text
This line consists of three expressions separated with semicolon. The comment “Ignore this text” is
ignored.
4.2 Expressions And Operators
19
The Amplifier language supports operators, which specify a mathematical, logical or
conditional operation/relation between two operands or more. Operands (actually
parameters) and operators may be combined in almost any way to create an expression. The
following paragraphs present the operators and the expression syntax rules.
4.2.1 Numbers
The Amplifier has two number types: 32 bit integers and 32 bit floating point numbers. As
text inputs, numbers that contain a decimal point or an exponent notation are interpreted as
floats. Other numbers are interpreted as integers.
The range for integers is [-2.1475e+009,+ 2.1475e+009].
Positive integers may be written as decimal or as hexadecimal.
The hexadecimal notation 0x10 is equivalent to the decimal number 16.
A 32-bit floating-point number has 24 significant mantissa bits and 8 bits of exponent.
The range for floating point numbers is [-1e20, 1e20].
A floating-point number may be written with or without an exponent.
2.5e4 is equivalent to 25000.0. It is not equivalent to 25000, since the latter number is
interpreted as integer.
If an integer number overflows integer range, it is interpreted as an error.
If a floating-point number overflows floating-point range, it is interpreted as an error.
Logical operators yield 0 or 1 as a result. The results of logical operators are integers.
4.2.2 Mathematical And Logical Operators
The following table lists the mathematical and logical operators of the language. The table
also specifies the operator precedence, which is discussed in the next paragraphs. The larger
number has the higher precedence.
Operator Description Precedence
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
+ Add two operands. 9
- Subtract the right operand from the left one. 9
* Multiply two operands. 10
/ Divide the left operand by the right one. 10
% Remainder after division two integers 10
^ XOR 1
~ Bitwise NOT of an operand. 11
& Bitwise AND between two operands. 5
| Bitwise OR between two operands. 4
<< Bitwise Shift left 8
>> Bitwise Shift right 8
== Logical equality 6
!= Logic not equal 6
< Logic smaller than 7
<= Logic smaller or equal 7
> Logic greater than 7
>= Logic greater or equal 7
&& Logical AND 3
|| Logical OR 2
! Logical negation 11
- Unary minus 11
= Assignment
() Parentheses, for expression nesting and function calls
[] Square parenthesis, for array indices and multiple value function
returns
20
Table 4-1 – Mathematical and Logical Operators
4.2.3 General rules for operators
4.2.3.1 Promotion to float and truncation to integer
Most the arithmetic operators work on both integers and floats. An arithmetic operation between integers
will yield integers, an operation between floating point numbers, or between an integer and a floating-point
number, will yield a floating-point result. For example, all the expressions below are legitimate:
1+2 (The result is 3, integer)
1+0x10 (The result is 17, integer) Note that 0x10 is treated as a standard integer.
1+2.0 (The result is 3.0, float)
2.1+3.4 (The result is 5.5, float)
The operation of division between two integers may yield a floating-point result in a case of division with
remainder. For example:
8/2 (The result is 4, integer)
9/2 (The result is 4.5, float)
If a result of multiplication between two integers overflows integer range
[-2.1475e+009,+2.1475e+009], this result will be converted into floating point, but won’t be truncated. For
example:
100000 * 100000 (The result is 10000000000, float)
Bit operators require an integer input. Floating-point inputs to bit operators are truncated to integers.
7.9 & 3.4 is equivalent to 7 & 3, since before applying the operator & (Bitwise AND) the floating point
number 7.9 is truncated to the integer 7, and 3.4 is truncated to the integer 3..
4.2.4 Operator details
The following paragraphs describe the operators in detail.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
4.2.4.1 Addition
Notation +
Description Arithmetic addition
Number of
2
arguments
Output type According to the section Promotion to float and truncation to integer
Example 4+5=9
3.45+2.78=6.23
4.2.4.2 Subtraction
Notation Description Arithmetic subtraction
Number of
arguments
Output type According to the section Promotion to float and truncation to integer
Example 4-5=-1
2
3.45-2.78=0.67
21
4.2.4.3 Multiplication
Notation *
Description Arithmetic multiplication
Number of
2
arguments
Output type According to the section Promotion to float and truncation to integer
Example PA=PA*2 doubles PA
5*4=20
1.5*2=3.0
4.2.4.4 Division
Notation /
Description Arithmetic division
Number of
2
arguments
Output type According to the section Promotion to float and truncation to integer
Example 20/4=5
3/1.5=2.0
4.2.4.5 Remainder
Notation %
Description Remainder after division two integers
Number of
arguments
Output type According to the section Promotion to float and truncation to integer
Example 20%4=0
2
5%2=1
4.2.4.6 XOR
Notation ^
Description Exclusive or, bitwise.
Number of
arguments
2
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Output type 32 bit long integer.
Example if x=1 as x^3=2
4.2.4.7 Bitwise NOT
Notation ~
Description Bitwise NOT
Number of
1
arguments
Output type 32 bit long integer.
Example ~3 is 0xfffffffc, which is actually –4
~3.2 is the same as !3
4.2.4.8 Bitwise OR
Notation |
Description Bitwise OR
Number of
arguments
Output type 32 bit long integer.
Example PA = 0x2 | 0x5 is equivalent to PA = 7
2
PA = 0x2 | 5.1 is the same
22
4.2.4.9 Bitwise AND
Notation &
Description Bitwise AND
Number of
2
arguments
Output type 32 bit long integer.
Example PA = 0x7 & 0x3 is equivalent to PA = 3
PA = 0x7 & 3.1 is the same
4.2.4.10 Logical Equality
Notation ==
Description Logical equality
Number of
2
arguments
Output type 0 or 1 (0 equals to false, 1 equals to true)
Example if x=3 and y=3 as x==y yields 1
if x=3 and y=5 as x==y yields 0
4.2.4.11 Logical Inequality
Notation !=
Description Logical inequality
Number of
arguments
Output type 0 or 1 (0 equals to false, 1 equals to true)
Example if x=3 and y=3 as x!=y yields 0
2
if x=3 and y=5 as x!=y yields 1
4.2.4.12 Logical Greater than
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Notation >
Description Logical greater than
Number of
2
arguments
Output type 0 or 1 (0 equals to false, 1 equals to true)
Example if x=3 and y=3 as x>y yields 0
if x=3 and y=2 as x>y yields 1
if x=1 and y=2 as x>y yields 0
4.2.4.13 Logical Greater than or equal
Notation >=
Description Logical greater than or equal
Number of
arguments
Output type 0 or 1 (0 equals to false, 1 equals to true)
Example if x=3 and y=3 as x>=y yields 1
2
if x=3 and y=2 as x>=y yields 1
if x=1 and y=2 as x>=y yields 0
23
4.2.4.14 Logical Less than
Notation <
Description Logical less than
Number of
2
arguments
Output type 0 or 1 (0 equals to false, 1 equals to true)
Example if x=3 and y=3 as x<y yields 0
if x=3 and y=2 as x<y yields 0
if x=1 and y=2 as x<y yields 1
4.2.4.15 Logical Greater than or equal
Notation <=
Description Logical greater than or equal
Number of
2
arguments
Output type 0 or 1 (0 equals to false, 1 equals to true)
Example if x=3 and y=3 as x<=y yields 1
if x=3 and y=2 as x<=y yields 0
if x=1 and y=2 as x<=y yields 1
4.2.4.16 Logical AND
Notation &&
Description Logical AND. The result is 1 if both arguments are nonzero, 0 if any is zero.
The arguments are not truncated to integers before evaluations
Number of
arguments
Output type 0 or 1
Example 1 && 5 yields 1
2
0.21 && 2 yields 1
0 && 2 yields 0
4.2.4.17 Logical OR
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Notation ||
Description Logical OR. The result is 1 if any of the arguments is nonzero, 0 if both are zero.
The arguments are not truncated to integers before evaluations
Number of
2
arguments
Output type 0 or 1
Example 1 || 0 yield 1
0 || 0 is 0.
4.2.4.18 Logical NOT
Notation !
Description Logical NOT. The result is 1 if the argument is zero, and 0 else
The arguments are not truncated to integers before evaluations
Number of
arguments
Output type 0 or 1
Example !4 yields 0
1
!0 yields 1
!0.0004 yields 1
24
4.2.4.19 Unary Minus
Notation Description Unary MINUS. The result is negative if the argument is positive, and vise
versa.
The arguments are not truncated to integers before evaluations
Number of
1
arguments
Output type The same as argument
Example -4.5 yields –4.5
-4 yields –4
(-4) yields 4
-5+5 yields 0
4.2.4.20 Bitwise Left Shift and Right Shift operators
Notation << or >>
Description The bitwise shift operators shift their first operand left (<<) or right (>>) by the
number of positions the second operand specifies.
The arguments are truncated to integers before evaluations.
Number of
arguments
Output type 32 bit long integer.
Example 8>>2 yields 2
2
8<<2 yields 32
4.2.5 Mathematical functions
The following table presents the mathematical built-in functions of the language.
Function names are case sensitive.
Operator Description Returns
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
sin Sine Floating point
cos Cosine Floating point
abs Absolute value Same type as input argument
25
sqrt Square root, or zero if argument is
negative
fix Truncate to integer.
fix(3.8) is 3
fix(-3.8) is -3
rnd Truncate to nearest integer.
rnd(3.8) is 4
rnd(-3.8) is –4
tdif Time difference
x=TM
tdif(x ) returns the time in msec since
x=TM has been sampled.
4.2.6 Expressions
An expression is a combination of operands (parameters) and operators that is evaluated in a
single value. Expressions work with immediate numbers, Amplifier commands, Amplifier
and global user-program variables.
There are different types of expressions, as described below.
4.2.6.1 Simple Expressions
A simple expression is evaluated in a single value. Any parameter and mathematical/logical
operator may be used to create a simple expression. Normally, simple expressions may be
used as a part of other types of expressions.
Simple expressions are evaluated according to the priority of the operators, as specified in
4-1 – Mathematical and Logical Operators. In case of equal priority, the expression is
Table
evaluated from left to right.
The use of parentheses is allowed to 16 nesting levels.
Example:
AC=100000
SP*2/5+AC
SP= SP*2/5+AC
IP|5
(SP+SP)*IA[1+AC*0]
IA[1]|5&2
2+3
1400000
Floating point
Integer
Integer
Floating point
4.2.6.2 Assignment Expressions
Assignment expressions are used to assign a value to variable or command. The syntax of an assignment
expression is:
<Parameter or command name>=<simple expression>
Example:
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
sp=sp*2/5+ac
op=ip|5
If the variable or the command is a vector, the assignment is allowable only for its single member. The
syntax of the vector member assignment is:
<Parameter or command name>[index]=<simple expression>
The index is an index of the relevant member vector. Indices are enumerated from zero.
Example:
ca[1] = 1
4.2.6.3 User variables
User variables are defined within a user program. The description and syntax rules of the variable definition
see at User variables of User Programming Language
User program variables may be used within the command line only if a program was compiled successfully
and downloaded to the Amplifier.
Through the Interpreter a user may inquire user variable value or change it.
A user has to pay special attention to the scope of a variable. A variable may be defined at the global or local
scope. The local variables are available only within the function where they are defined, while the global
variables are available within any function and outside a function.
A user variable may be inquired or changed when the program is in the running or halt status.
For example, suppose that a compiled program includes the following lines at the global scope:
int ZEBRA,GIRAFA[3];
float GNU;
Then the expression
GNU=ZEBRA*GIRAFA[1]+2*sin(GIRAFA[2]);
is valid. User program variables are case sensitive.
26
4.2.6.4 Built-in Function Calls
The built-in function call may be used in a single expression. For a list of built-in-functions refer
Mathematical Functions
The built-in function call may be a part of a single expression.
Example:
sin(3.14/2)
AC=abs(DC)
SP=SP+sin(3.14/2)
4.2.6.5 Time functions
Use the TM command to read the system 32 bit microsecond counter.
The time difference from the present time to an older sampling of TM can be taken in two methods:
Example
QP[1] = TM ; ** QP[1] is used just as storage
…. ** Do something
QP[2] = QP[1]-TM ; ** QP[2] is time difference in microseconds.
Example
QP[1] = TM ; ** QP[1] is used just as storage
…. ** Do something
QP[2] = tdif( QP[1]) ; ** QP[2] is time difference in milliseconds.
Time differences cannot be taken longer then 31 minutes.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
4.2.6.6 User Function Calls
The XQ command enables a user function call. See Running of a User Program
A user function cannot be called from the command line without the XQ command.
4.3 Comments
Comments are texts that are written into the code to enhance its readability.
A double asterisk marks comments. The comment starts in a double asterisk comment marker, and
terminates at the next end of line.
The Amplifier ignores the comments when evaluating an expression.
Example:
mo=1; **motor on
This example demonstrates that a comment may start anywhere in the program line. The MO=1 instruction
preceding the comment marker shall be executed.
Remark: Comments in the command line differ from comments in a user program. User Program Language
has three methods to write comments, while the Interpreter Language has the only one.
27
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
5 The Harmonica User Programming Language
This chapter describes the Harmonica user language in detail.
This chapter is somewhat out of place, since the user program language is not really a feature of the
Harmonica.
The Harmonica can only understand virtual assembly commands – see commands at the chapter The Virtual
Machines: Short reference.
The Compiler translates user language into virtual assembly commands. It reads user program and
transforms it to the sequence of simple virtual assembly commands. The compilation process runs off-line in
the PC, not inside the Harmonica. Before the Harmonica executes a user program, it must be preliminarily
compiled and the compiled code must be downloaded to the serial flash of the Harmonica. A little more
about the Compiler see at the section Compilation
An Amplifier program is a list of commands in certain order. A user program can be anything from a simple
list of commands to a very complicated machine management algorithm.
The section below describes how to write, maintain, and run user programs for the Amplifier.
5.1 User Program Organization
A user program is organized as follows:
•
Integer and floating point variable declarations
•
Program text, including expressions, commands, labels, and comments
•
An exit directive may be used to terminate the program.
Most of the interpreter commands can be used in the program text. In order to learn if a
given interpreter command can be used in a program, please refer the scope attribute of that
command in the Command Reference Manual.
The Interpreter commands that cannot be used in a program are:
•
Commands that upload or download data between the Amplifier and its host.
•
Commands that store data in the flash memory, or that retrieve data from the flash memory.
•
Commands concerning the execution of the user program.
In addition to the interpreter commands, a program may include program flow statements
that manage how the program runs.
•
Iterations.
•
Subroutine execution commands.
•
Conditions.
In the program text, semicolons, commas, line feeds or carriage returns separate the
commands.
A single program line is executed as a one unit, preventing intervention from the interpreter
or a CAN command.
For example in the sequence
UM=5;
MO=1;
It is possible that an interpreter command shall be executed between the execution of the
two program statements. If the interpreter statement was UM=2, then MO=1 is specified for
a wrong unit mode. The sequence
MO=0;UM=5;MO=1;BG
Guarantees that MO=1 is executed with the correct unit mode.
Example 1:
int x,k; Variable declarations
##Foo Label definition
28
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
X=0; Initialize
for k=0:10 Iterate
X = x + 1 ; Do something
end End of iteration
exit End of program directive
##Moo
... More code
The program defines two variables named x and k.
##Foo is an entry point.
After compilation, it is possible to run this piece of code by commanding XQ ##Foo to the interpreter.
When the program starts at ##Foo, it clears the user variable x. It then iterates 11 times, incrementing x with
every iteration. Finally, x = 11.
The exit command terminates program execution.
Another code section can be executed by commanding XQ ##Moo.
Example 2:
29
switch (IP & 3) Select according to the two low input bits
case 1
PR=1000; If value is one...
case 2
PR=500; If value is two ...
otherwise
PR=100; Otherwise...(Last two bits are 0 or 3)
end
BG Begin motion
This example moves an axis with a step that depends in the state of the digital inputs.
5.2 Common
A user program contains lines of text code. This text must have defined syntax for the Compiler to recognize
it. This section contains some common description of a program text.
5.2.1 Line and Expression Termination
A line has the following terminators: carriage return, line feeds or their combination.
A line can contain a single expression or sequence of expressions. Sequence of expressions in the same line
can be separated with semicolon or comma (not inside round or square parentheses).
Example:
a = 3 , b = 2 , c = a + b , ** This line consists of three expressions separated with comma
a = 3 ; b = 2 ; c = a + b ; ** This line consists of three expressions separated with semicolon
a = 3 , b = 2 ; c = a + b ** This line consists of three expressions separated with comma, semicolon and
terminated with line feed
[a,b] = foo (23, c, 3.14) ** In this expression comma is not expressions separator, because it is inside
parentheses
5.2.2 Line Continuation
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
A user program may contain too long line and its representation at the screen may be not convenient,
because not all symbols are shown at the screen. In order to improve readability of the program, a user may
continue this expression at the next line. Three points at the end of line indicates that this line will be
continued.
Example:
Assume that a user program contains the next expression
c = 12 * a + sqrt(2) – sin(3.14 / 2) + 7 ^ 3 * …
(6 + b) * 34
Three points at the end of the first line shows that this expression is not finished and is continued at the next
line.
5.2.3 Limitations
Every line of a user program text may contain 128 characters as maximal length (for better readability at the
screen). For too long text line (more than 128 symbols) the Compiler sets an error.
Expressions also have limitation: the maximal admissible length of expression is 512 symbols, not including
comments. If a program contains complex expression that takes some lines and the summary length of
expression without comments and three points exceeds 512 symbols, then the Compiler sets an error.
There are some limitations of a user program text depending on the specified Harmonica device. The list of
setup parameters of the Harmonica, which are limiting a user program, is represented below.
•
Maximal length of user program text
•
Maximal number of routines, including functions, labels and auto routines
•
Maximal number of variables, including as global as local
•
Maximal length of the data segment – space for storage of global variables
•
Maximal length of the code segment – space for compiled code
•
Maximal depth of the stack – working space of the program
The IDE enables a user to see these parameters (not implemented yet). Ask Ilia and Nicolay
30
5.3 Expressions And Operators
5.3.1 Numbers
The number syntax is the similar to the Interpreter Language (see Number of the Interpreter Language ), but
there are some differences in evaluation of immediate numbers. User program is compiled at the PC in offline mode, so it has more resources, than the Interpreter.
The range for floating point numbers is [-1e38,+1e38], it is more than the Interpreter language numbers
have.
If an integer number overflows integer range, it is converted to float (the Interpreter interprets it as an error).
If a floating-point number overflows floating-point range, it is interpreted as an error.
5.3.2 Mathematical and Logical Operators
The description and syntax is the same as in the Interpreter Language. See Operators of the Interpreter
Language
5.3.3 General rules for operators
The description and syntax is the same as in the Interpreter Language. See General rules of the Interpreter
Language
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
5.3.4 Operator details
The description and syntax is the same as in the Interpreter Language. See Operator details of the Interpreter
Language
5.3.5 Mathematical functions
The description and syntax is the same as in the Interpreter Language. See Mathematical functions of the
Interpreter Language
5.3.6 Expressions
5.3.6.1 Simple Expressions
The description and syntax is the same as in the Interpreter Language. See Simple Expressions of the
Interpreter Language
5.3.6.2 Assignment Expressions
The description and syntax is the same as in the Interpreter Language. See Assignment Expressions of the
Interpreter Language
User programming language allows multiple assignment to multiple output of the function. Syntax and
descrition see at the section
31
5.3.6.3 User variables
User variables are defined within program, using the int or the float declarations.
The keywords for variable types are ‘int’ and ‘float’.
Syntax:
int int_var1, int_var2[12], …, int_varN;
float flt_var1[13], flt_var2, flt_varN;
int a;
float b;
Variable must be declared before its use (in the expression or assignment).
The definition line of variables consists of type name (int or float) and variable names.
Variables at the definition line must be separated with comma or every variable may be declared at the
separate line. Variables may be scalar, or vector. If a variable is a vector, it must be declared its dimension in
square brackets after its name.
Only global variable may be one-dimensional array. Neither local variable nor input/output argument of a
function can be a vector.
Dimension of the vector must be positive constant number. If dimension is defined as floating-point number,
it will be truncated to integer. The dimension that is less than one is illegal.
For example,
int arr[12.5] ;
The floating-point number that defines dimension will be truncated to 12.
int arr[-2] ;
This variable definition is illegal, because dimension is negative.
Local variables must be defined at the beginning of function bodies. Any local or global variable definition
after some executable code of the function is illegal.
For example,
function foo (int a) ** Function definition
int b ; ** Local variable definition
b = a ; ** Executable code
float c ; ** Local variable definition
Definition of the variable ‘c’ is illegal, because it is after some executable code.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
The names of variables may include ASCII letters, digits (not leading) and underscores (not leading) only.
It’s case sensitive. The maximal variable name length is 12 characters.
A variable name cannot be a keyword.
The list of the keywords is as follows:
“int”,
“float“,
"if",
"else",
"elseif",
"for",
"while",
"switch",
"case",
"otherwise",
"break",
“end”,
“return”,
“function”,
“global”,
"keyboard",
"exit",
"virtual",
"all",
"reset",
"wait",
"until",
"goto",
“nargout”,
“halt”
The all keywords are case sensitive.
Variable name must be distinct from some function or label name.
After a program is compiled, all the program variables may be used within the command line.
For example, assume that a compiled program includes the following lines:
int ZEBRA,GIRAFA[3];
float GNU;
Then the expression
GNU=ZEBRA*GIRAFA[1]+2*sin(GIRAFA[2]);
is valid. Variables are case sensitive.
More about global and local variables see at the sections Automatic Variables
and Global Variables
32
5.3.6.4 System Commands
The Harmonica system commands are described at the Command Reference.
System commands description in this section is designed only to explain their use in user program.
System command has two-letter mnemonic notation (only English letters, case not sensitive).
For example,
ac = 100000
AC = 100000
Both these expressions have the same meaning, in spite of different notation.
Every command has the 16-bit flag, every bit of which defines any feature.
For example, the fourth bit (PostProcess flag) defines whether this command can be used to set value or not.
List of commands depends on the specified Harmonica.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Consider some examples using system commands.
Example Explanation
a = AC This expression assigns value of the system command AC to the variable ‘a’.
This expression is valid if the AC command is allowed to ‘get value’, i.e. it has PreProcess flag
AC = a This expression assigns value of the variable ‘a’ to the system command AC.
This expression is valid if the AC command is allowed to ‘set value’, i.e. it has PostProcess flag
BG This is executable command. It cannot be assigned, i.e. it has neither PreProcess nor PostProcess
nor Assign flags
For example, the following expressions
BG = 1
or
a = BG
are not legal
LS This expression is not legal, because it uses command that has NotProgram flag. The
‘NotProgram’ commands are not allowed in user program, while they are available for the
Interpreter language.
5.3.6.5 Built-in Function Calls
The description and syntax is the same as in the Interpreter Language. See Built-in function call of the
Interpreter Language
33
5.3.6.6 User Function Calls
Functions perform a pre-written and compiled code. Functions get a list of arguments from their caller, and
return a list of return values.
Functions get their list of input argument by value – they do not directly modify them.
The general syntax of a function call is
[OUT1,OUT2,…OUTN]=FUNC(IN1,IN2,…IN_N)
If only one value is returned, the square parentheses are not required and the syntax is following:
OUT=FUNC(IN_1,…,IN_N)
Not all the output variables need be assigned.
For example, if the function FUNC returns two values,
[IA[1],IA[2]]=FUNC()
assigns the two returned values to IA[1] and IA[2].
IA[1]=FUNC()
Returns the first return value to IA[1], and the other returned values remain unused.
If the returned value has another type than variable that receives it, the result shall be type cast to the type of
the variable.
Numbers of input arguments during function call are strict according to its definition.
If function call is a part of expression, then multiple output of the function is illegal.
For example,
[a, b] = 5 + foo(c)
or
[a, b] = foo(c) + 5
Both these expressions are not legal: function call is a part of expression and must be evaluated in a single
value.
5.4 Comments
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Comments are texts that are written into the code to enhance its readability. There are three methods to write
comments.
A double asterisk marks comments. The comment starts in a double asterisk comment marker, and
terminates at the next end of line.
The Amplifier ignores the comments when running a program or evaluating an expression.
Example:
**my first program
PX=1
**um=5
mo=1; **motor on
In the above example program, the first line is a comment used to enhance program readability. The
comment terminates at the next end of line, so the next PX=1 instruction shall be compiled and executed.
In the third line, the comment mark tells the Amplifier to ignore the UM=5 command. This technique is
useful for temporarily masking program lines in the process of debugging.
The last line demonstrates that a comment may start anywhere in the program line. The MO=1 instruction
preceding the comment marker shall be compiled and executed.
A percent sign (the MATLAB style) marks comments in the same way as a double asterisk. The comment
starts in a percent sign comment marker, and terminates at the next end of line.
Example:
%my first program
PX=1
%um=5
mo=1; %motor on
In this example a percent sign marker just changes a double asterisk marker from the previous example to
show that both of them have the same use.
Another commenting method is the C style. A C style comment starts with the start comment mark /* and
terminates with the end comment mark */. The C style enables closing a text in the middle of an expression,
or closing several text lines.
Example:
/*
This is a multiple line comment.
All this text is ignored.
*/
if ( 1 /* x == 1 */ )
y = 1;
end
The expression y = 1 will be always executed. The x==1 condition enclosed by the comment markers is
ignored.
34
5.5 Program Flow Commands
The Amplifier has a set of commands that manage the flow of the user program.
With the aid of these commands, the user program can make decisions iterate, or respond automatically to
some events.
The program flow commands enable user programs to do much more complicated things then just running a
set of commands sequentially.
The program flow commands are:
while – end : Iterate as long as a condition is satisfied.
until : Iterate (suspend the execution of the program) until a condition is satisfied.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
wait : Iterate (suspend the execution of the program) until a specified time is elapsed.
for - end : Iterate counted times
break : Break an iteration or a switch expression (for, while, switch)
if – else – elseif – end: Conditional expression.
switch-case-otherwise-end: Case selection
goto – Go to some point in the program
reset – Kill the state of the executing program and jump to some point in the program.
function-return – Declare a function and its return point
##: Declare a label or an auto routine
#@: Declare a label or an auto routine
#@ - return: Declare an auto routine and its return point
exit – Terminate program execution.
5.5.1 Labels (Entry points)
Labels denote that program execution can start from that place, or that program execution can be branched to
that place.
Label definition has the following syntax:
##<LABEL_NAME>
or
#@<LABEL_NAME>
A maximum of 12 characters (letter and/or digit (not leading) and underscore (not leading) only) may be
used for label. A name of label must be distinct.
Labels can reside inside or outside function bodies, but not within a program flow structure, such as a for
iteration.
Labels inside function bodies regard as local of the function and serve as targets for goto instructions within
the same function.
Labels in the global text scope serve as possible execution starting points, and also as targets for reset and
global scope goto.
The XQ and the XC program launching commands use labels to specify where to start program execution
and were to terminate. For example, if user wants to start execution at ##LOOP2, he can do it by sending the
command
XQ ##LOOP2
Example:
##START; The program start
##LOOP1; A label
…. The body code A
goto##LOOP1;
##LOOP2;
….. The body code B
##LOOP3;
…
35
According to above example, if the program runs from label ##START, the body code A will be performed
forever. The ##LOOP2 will never be reached.
5.5.2 For iteration
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Perform an indexed iteration in a program.
Syntax:
for k=N1:N2:N3
…
end
or
for k=N1:N2
…
end
where N1, N2, and N3 are numbers or simple expressions.
The syntax:
for k=N1:N2:N3
…
end
iterates k from N1 to N3 with a step of N2.
The syntax:
for k=N1:N2
…
end
iterates k from N1 to N2 with a step of 1.
Notes:
1. If the iteration step is zero, the program is aborted with the error code
INFINITE_LOOP.
2. If N1, or N2, or N3 are variables, they are evaluated once before the iteration
begins. If the variable changes within the "for" loop, the iteration process will not be
affected.
3. Iteration variable k must be declared as a variable.
Example:
36
…. Start user program or function
float ra[20]; Float array declaration
int ia[20]; Integer array declaration
int k; Variable declaration
…
for k=1:10 Start of iteration loop
ia[k]=100; Update the first ten elements of the integer
ra[k]=55.55; Update the first ten elements of the real array
…
end End of iteration loop
….
5.5.3 While iteration
array
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Syntax:
while( expression )
…
statement
…
end
The while keyword executes statement repeatedly until expression becomes 0.
The expression can be logical or/and numerical.
Note: expression may be within round parentheses or without ones.
Example:
OB[1]=0 Digital output 1 is OFF
while(IB[1])
OB[1]=1 While the digital input 1 is ON, the digital
output 1 is ON
end
OB[1]=0; Digital output 1 is OFF
….
…
While (IB[2])
end
MO=1; This command will be performed only after
digital input 2 is OFF.
37
5.5.4 Until iteration
Syntax:
until (expression ) ;
The until keyword suspends the execution of the program until expression becomes true (nonzero).
The expression can be logical or/and numerical.
Example:
Assume that user wants to suspend the program until the variable PX exceeds 20000 and digital input 1 is
ON.
The code below has the same functionality
…
until (( PX==2000)&IB[1]) ;
…
The until expression may be useful to synchronize threads for amplifiers that support multithread programs.
For example, we have two threads. Assume that the second thread must start after the first thread finishes
some work. We define a global variable, which shows whether the first thread finished or not. The second
thread is suspended by until expression.
We first define a variable:
int IsFirstFinished ; **The global variable definition
The variable is initially set to zero.
The code of the first thread shall be:
…
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
… Do some work …
IsFirstFinished = 1 ; **Signal that some work is completed
The code of the second thread will include
… Prior to suspension code
until (IsFirstFinished) ; **The second thread suspended until
**signal
… Continue program.
If we want to suspend thread without terminating it, we can use until with a false expression.
5.5.5 Wait iteration
Syntax:
wait (expression ) ;
The wait keyword suspends the execution of the program until the specified time is elapsed.
The expression may be within round parentheses or without ones.
The expression specifies the waiting time in milliseconds. It can be numerical expression only,
which is evaluated in a single value.
Example:
PA=10000
BG
until (MS == 0)
wait (20) ; Wait 20 milliseconds
38
The above program instructs a PVT motion. The until (MS == 0) waits until the position command is
stabilized at the new position. The wait (20) allows additional 20 milliseconds for final stabilization.
5.5.6 IF condition
Syntax:
if( expression1 )
…
statement1
…
elseif ( expression2 )
…
statement2
…
else
…
statement3
…
end
The if keyword executes statement1 if expression1 is true (nonzero); if ifelse is present and expression2 is
true (nonzero), it executes statement2. The ifelse keyword may repeat scores of times during to if condition.
The statement3 will be executed only if all expression1, expression2, … expressionN
are false( or zero).
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Example:
if (IB[4])
PR=1000; PR=1000 only if digital input 4 is ON
elseif(IB[3])
PR=5000; PR=5000 only if digital input 3 is ON
elseif(IB[2])
PR=3000; PR=3000 only if digital input 2 is ON
else
PR=500; PR=500 only if digital input 2,3 and 4 are
OFF
end
5.5.7 Switch selection
Syntax:
switch( expression )
case (case_expression1)
statement1
case (case_expression2)
statement2
……
otherwise
statement
end
The switch statement causes an unconditional jump to one of the statements that is the “switch body,” or to
the last statement, depending on the value of the controlling expression, the values of the case labels, and the
presence or absence of an otherwise label.
The switch body is normally a compound statement (although this is not a syntactic requirement). Usually,
some of the statements in the switch body are labeled with case labels or with the otherwise label. Labeled
statements are not syntactic requirements, but the switch statement is meaningless without them. The
otherwise label can appear only once. Before the otherwise label must be at least one case label.
In contrast to the case label, the otherwise label cannot be followed by any expression for evaluation.
The switch and case expression may be any logical or/and numerical expression.
The case-expression in the case label is compared for equality with the switch-expression.
If the switch expression and the case expression are equal, then this case is selected and the statements
between the matching case expression and the next case or otherwise label are executed. After the execution
of the statements may appear the keyword ‘break’. But it is not necessary to finish the statements of a single
case with break, because after the execution of the statements an unconditional jump to the end of the
switch is performed automatically.
If there are some case expressions that match to the switch expression, then the first matching case is
selected.
Example:
The following example selects the size of a point-to-point motion according to the value of the variable k.
int k The variable declaration
…
39
Elmo HARmonica Software Manual
HARSFEN0602
switch (k) For example, k=2
case 1
PA=1000;
case 2
PA=2000; This statement will be performed
otherwise
PA=500; If k doesn’t equal to 1 or 2 , pa=500
end
5.5.8 Break
Syntax:
break
The break statement terminates the execution of the nearest enclosing for, switch or while statement
in which it appears. Control passes to the statement that follows the terminated statement. The break
statement is outside of for, switch or while statements is illegal.
Example:
P R E L I M I N A R Y D R A F T
40
…
while (IB[2]) Loop until digital input2 is ON
if (!IB[1])
break; Break the loop when digital input 1 is OFF
end
MO=1; This command will be performed only after
digital inputs 1 or 2 are OFF.
…
5.6 Functions
5.6.1 Function definition
Functions are program sections that can be parameterized and called from anywhere in the program.
Function declaration consists of the following parts:
1. Reserved keyword function
2. List of output arguments with their types in square brackets– optional
3. Assignment sign – only if there is some output argument
4. Function name
5. List of input arguments with their types in round brackets. List of input arguments may be empty.
For example,
function [int y1, int y2] = func1 (float x1, int x2) This function is named func1, it gets two input
1
arguments x1 and x2 and returns two output arguments
List of output argument may be empty. In this case 2 and 3items are absent or it can be empty square
brackets. If there is the only output argument it can be without square brackets.
Maximal admissible number of input and output arguments is 16.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
For example,
function func2 (struct float x1) This function is named func2, it gets the only input
2
argument of float type and doesn’t return any output.
3 [int y1] = func3 (int x1)
This function declaration is illegal, because keyword
function is absent
4 function y1 = func5 This function prototype is illegal, because type of the
output variable is absent.
The valid function name observes the same rules as the variable name. It must be distinct from any variable,
function or label name.
Definition of dimensions of the output and input arguments at the function declaration is illegal.
For example,
function [int x[100]] = func3 () This function declaration is illegal, because
5
dimension of output argument is defined.
Function may have prototype before its declaration. The prototype has the same syntax with function
declaration, but it must end with semicolon.
For example,
6 function [float y1] = func4 () ;
This is prototype of function func4 that doesn’t
has any input argument and returns the only
output argument
7 function float y1 = func4 ; It’s the same as the previous example 6.
8 function float = func4 ;
This function prototype is the same as example
6 and 7. Name of input or output argument of
the function prototype may be absent, while
during definition of the function it’s error.
9 function [int, int] = func1 (float, int) ; This is prototype of the function from the
example 1. It’s the same as
function [int y1, int y2] = func1 (float x1, int
x2) ;
It is allowed to write the prototype of the same function several times (multiple prototype), but all these
prototypes must be identical. The names of the input/output arguments in the function prototype may be
omitted, or may be different from the name of the corresponding argument names in the function declaration.
For example,
10 function [int y1, int y2] = func
(float x1, int x2) ;
function [float y1, int y2] = func
(float x1, int x2)
11 function [int y1, int y2] = func
(float x1, int x2) ;
function [int a, int b] = func (float
The first expression is the function prototype and
the second is the function definition.
It’s not legal, because types of the first output
argument in the prototype and declaration do not
match.
The first two expressions are the function
prototype and the third is the function definition.
It is legal
x1, int x2) ;
function [int y1, int y2] = func
(float x1, int x2)
Body of a function resides below the declaration and must end with the keyword return. If the keyword
return is inside some control block within the function body, it is not the end of the function body.
For example,
12 function [int y1, int y2] = func
(float x1, int x2)
** Function definition.
41
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
y1 = x1; ** Function body
y2 = x2;
if x2 > 0 ** If block
return ** return inside block is not the end of the
function
end ** End of if block
y2 = y1 + y2 ; ** Some executable code
return ** Function end
Before function call, it must be declared. It may be either function prototype or function definition.
For example,
13 function [int y1, int y2] = func
(float x1, int x2) ;
** Function prototype.
…
function main() ** Function main definition
int a, b; ** Local variable definition
[a,b] = func(2.3, -9.0); ** Function call
return ** Function main end
…
function [int y1, int y2] = func
** Function definition
(float x1, int x2)
… ** Function body
return ** Function end
If any function declared without body, its call is illegal.
For example,
14 function [int y1, int y2] = func
(float x1, int x2) ;
** Function prototype.
…
function main() ** Function main definition
int a, b; ** Local variable definition
[a,b] = func(2.3, -9.0); ** Function call
return ** Function main end
…
In this example function func has prototype, but has no body, so its call is illegal.
42
5.6.2 Dummy va riables
The input arguments and the output arguments of a function are called dummy variables. A
true variable is substituted for the dummy variable when a function is called.
Example: In the example of the statistic function from the next chapter, variables mean and std are the
dummy variables.
5.6.3 Count of output variables
A function may return multiple values. In some cases, not all the outputs need be computed. A function can
use the nargout keyword –to know how much of its results it actually needs to evaluate.
Number of outputs is the number of items in the left hand side expression during the function call. If its
number exceeds the number of maximal defined output arguments of this function or the maximal
admissible number of output arguments, it’s an error.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
If some function does not return any output by its definition, then zero value as output will be inserted to the
stack actually. Assume that the function foo is declared with no output arguments. So the following
expression:
foo () + 3 is legal, because foo returns zero by default.
Example:
float vec[11], RA[100]; Declare the global variables
float value; Declare the global variable
function [float mean, float std]=statistic(); Prototype of the function
...
[RA[1],RA[2]]=statistic() Calling the STATISTIC function. After
executing RA[1] will be equal to variable
MEAN and RA[2] will be equal to variable
STD
[value]= statistic() In this case, after executing the STATISTIC
function VALUE will be equal to variable
MEAN
…
function [float mean, float std]=statistic() Declaration of a function that calculates mean
and standard deviation of the global vector
vec.
int k; Declare k as automatic variable
global vec[11]; Redeclaration for vec variable (vec is the
global variable that is declared before)
mean=0;
for k = 1:10
mean = mean + vec[k];
end
mean = mean/10; Calculate mean of vec[]
if ( nargout > 1) Only if the standard deviation is asked...
std = 0 ;
for k =1:10
std = std + vec[k] * vec[k] ;
end
st = (1/10)* sqrt( std – 10 * sum)
end
return End of the function body
…
43
Count of input arguments
The number of input arguments during function call must be the same as it is declared during function
definition.
5.6.4 Automatic variables
A variable declared within a function is automatic. It is generated when the function is
called, and it ceases to exist when the function exits.
At the time of function call, all its automatic variables are set to zero. When the function
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
exits, the value of the automatic variables is not saved.
Automatic variable cannot be a vector.
Example: In the example of the STATISTIC function, variable k is the automatic variable
5.6.5 Global variables
A function can refer a persistent variable. In this case the referred persistent variable must be
declared global inside function and must be defined above function definition. The global
keyword is obligatory; otherwise the variable will be referred as an automatic variable of the
function.
The dimension of a persistent variable is defined once a program during its definition and
the same for this global variable in all functions where it is used. The legal way to declare
the dimension of a persistent variable inside function is empty square brackets after its name
or absence any brackets.
Example: In the example of the STATISTIC function, variable vec[11] is the global
variable. It is defined above the function definition and inside the function body it is
redeclared as global.
float temp; Declare the global vector variable
int vec[10] ; Declare the global vector variable
…
function [float a]=func(int b ) Declaration of a function func
float temp ; Declare temp as an automatic variable,
because the global keyword is absent.
… Function body
return The end of the function
…
function [float a]=func1(float temp ) Declaration of a function func1. In this case
temp is not global variable, but an input
argument.
…
return The end of the function
…
function [float a]=func2(float b ) Declaration of a function fun2.
global float temp ; Redeclaration of the global variable temp. In
this function temp is the global variable.
global int vec[] ; Redeclaration of the global variable vec.
Notice that its dimension is omitted during
redeclaration and its actual dimension is 10 as
it is defined above.
44
5.6.6 Jumps
Syntax:
goto ##LABEL1
The jump (goto) command instructs the program to continue its execution at the label
specified by the jump command.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
The goto comm and may be specified only for destinations within the present function scope.
It is not possible to jump to labels that are inside another function.
The jump to the global label from within some function is illegal.
Example:
… **Working code
if (PX>1000) **Condition for jump
goto##LABEL1; **Go to LABEL1 if the condition is true
else **Return axis to origin
goto##LABEL2; **Go to LABEL2 if the condition is false
end
… **Working code
##LABEL1; LABEL1 declaration
…. **Working code
##LABEL2; LABEL2 declaration
… **Working code
5.6.7 Functions and The Call Stack
45
A function is a piece of code that may be called from anywhere in the program. After the
function is executed, the program resumes from the line just after the function call.
Example:
function JustSo ; **function prototype
…
JV=1000
JustSo() **function call
BG
…
function JustSo **function definition
IA[0]=1; **function body
return **function end
The above code will execute the sequence
JV=1000;IA[0]=1;BG;
After executing JV=1000, the program jumps to the subroutine JustSo. Before doing so, it stores its return
address. The return address is the place in the code where execution is to resume after the routine is done. In
this example, the return address is the line number of the instruction BG, which is just after the subroutine
call.
The return command instructs the program to resume from the stored return address. After the execution is
resumed at the return address, the return address is no longer required, and it is not stored any more.
Functions may call each other – in fact, they may even call themselves. The return addresses for nested
function calls are stored in a call stack, as shown in the example below.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Example:
function factorial() ; **Function prototype
…
IA[1]=3
IA[2]=1
factorial() **Function call
BG
…
function factorial() **Function for factorial
global int IA[] ; **Definition of array as global inside function
IA[2]=IA[2]*IA[1] **Recursive algorithm
IA[1]=IA[1]-1
if ( IA[1] > 1 ) factorial() ; end **Recursive call
return **Function end
The factorial function of the example calculates the factorial of 3 in IA[2]. The variable IA[1] counts how
many times the function factorial is executed.
The program executes as follows:
Code IA[1] IA[2] Call stack
IA[1]=3 3 Undefined Empty
IA[2]=1 Unchanged 1 Empty
factorial Unchanged Unchanged
→
BG
IA[2]=IA[2]*IA[1] Unchanged 3 Unchanged
IA[1]=IA[1]-1 2 Unchanged Unchanged
if ( IA[1] > 1 ) factorial() ; end Unchanged Unchanged
→
→
RT
BG
IA[2]=IA[2]*IA[1] Unchanged 6 Unchanged
IA[1]=IA[1]-1 1 Unchanged Unchanged
if ( IA[1] > 1 ) factorial() ; end Unchanged Unchanged Unchanged (condition is
false)
return
Unchanged Unchanged
→
BG (Program jumps to
the return which was on
top the call stack)
return
Unchanged Unchanged Empty (Program jumps to
the BG which was on top
the call stack)
BG Unchanged Unchanged Unchanged
46
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
5.6.8 Killing The Call Stack
In some rare situations, it is desirable to exit a function without returning to its return
address. The reset instruction solves this problem by emptying the call stack before making
a jump.
Syntax:
reset <JUMP_NAME>
The valid jump after the ‘reset’ keyword is one of the following:
1. label
2. auto routine
3. user function with no defined input arguments
All other expression or absence of expression after the keyword ‘reset’ is illegal.
Remark: Label in reset instruction must be global. Local label is illegal, because the stack will be
emptied and all local variables and return address of the function to whose the local label belongs
will be erased.
Example:
Assume that an Amplifier (an axis) runs a programmed routine.
An inspection station may assert a “Product defective” digital signal.
The “Product defective” signal is coupled to the digital in#1 input.
An automatic routine is coupled to the digital in#1 input, to stop the part assembly and get ready for the
assembly of the next part.
##START_NEW **Label for starting a new part
… **Working code
… **Last line of working code
#@AUTO_I1 **Subroutine label
PA=0;BG **Return axis to origin
reset START_NEW **Clear the stack and go to the beginning
The reset in the #@AUTO_I1 routine is required since we do not know if any function calls are
executing when Digital In #1 is asserted. If a function was executing, the reset prevents junk
gathering in the call stack. Otherwise, the call stack wa s em pty and the reset does no harm. Note that
after the reset control does not return to the function which was executing before Digital In# is
occurred. Stack was cleared and the return address to the interrupted function was removed from the
stack.
Note
The #@AUTO_I1 routine is executed after the work code is done for every assembled part.
The program proceeds from the last line of the working code to PA=0;BG, which resets the
machine for another part assembly. The next instruction is a reset to the START_NEW
label.
47
5.6.9 Automatic subroutines
5.6.9.1 List Of Automatic Routines
A special kind of routine is the auto routine. These routines are executed automatically
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
according to system events. These routines will be executed only when their invocation
condition is satisfied. These automatic routines doesn’t have output and input arguments.
Syntax:
There are two options to define an auto routine: either as a function or as a label.
If it’s defined as a function, then all syntax rules for function definition are relevant (see the
chapter Function definition
).
An auto routine may be defined as a label: its name follows the sequence of characters ## or
#@ in the definition line. The body of the auto routine is between the definition line and the
keyword ‘return’ unless this return is inside some flow control block.
Note:
The keyword ‘return’ instructs after execution of an auto routine to return to the next line in
the code, where execution was halted by interrupt event.
After call such routine and performing its body, the program will return to the next line in
the code, where execution was halted by interrupt event.
There are no default handlers for auto routines. If a user does not define automatic routine,
then any handling will not be activated when an automatic event is asserted.
Routine name Priority
AUTOEXEC
AUTO_ER
0
1
AUTO_STOP
2
An autoexec code is executed automatically
upon power on. An autoexec function can be
called later any time.
A motor fault event, in which MO=0 is set
automatically.
Called when a digital input configured to the
“Hard-Stop” function is activated. Refer the IL
Activated by Mask (MI)
1
2
4
command.
AUTO_BG
3
Called when a digital input configured to the
“Begin” function is activated. Refer the IL
8
command.
AUTO_RLS
4
Called when a digital input configured to the
“RLS” function is activated. Refer the IL
16
command.
AUTO_FLS
5
Called when a digital input configured to the
“FLS” function is activated. Refer the IL
32
command.
AUTO_ENA
6
Called when a digital input configured to the
“Enable” function is activated. Refer the IL
64
command.
AUTO_I1
7
Called when a digital input #1 configured to the
“GPI (General purpose Input)” function is
activated. Refer the IL command.
128
Called when a digital input #2 configured to the
AUTO_I2 8
“GPI (General purpose Input)” function is
256
activated. Refer the IL command.
AUTO_I3 9
Called when a digital input #3 configured to the
“GPI (General purpose Input)” function is
512
activated. Refer the IL command.
AUTO_I4
10
Called when a digital input #4 configured to the
“GPI (General purpose Input)” function is
1024
activated. Refer the IL command.
AUTO_ I5
11
Called when a digital input #5 configured to the
“GPI (General purpose Input)” function is
activated. Refer the IL command.
2048
48
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Called when a digital input #6 configured to the
AUTO_ I6 12
“GPI (General purpose Input)” function is
4096
activated. Refer the IL command.
Table 5-1 – Automatic subroutines and their priority
All the automatic routines, except AUTOEXEC, are activated only if a program is running.
Example:
Consider the program
##LOOP
**A go forever loop
gotoLOOP
#@AUTO_I3 **Subroutine definition
… **Subroutine body
return **Subroutine end
The forever loop in the first two lines of the routine is intended to make the program run forever, so that the
automatic routine will be able to handle the digital input #3 event.
The #@AUTO_I3 routine will be called if digital input #3 is sensed and not masked.
The digital input #4 will not invoke any automatic action in the user program, since no #@AUTO_I4 routine
is defined to handle digital input #3 event. A user has an option for explicit call of an automatic routine, if it
is desired. The syntax for an auto routine call is the same as for a user function.
49
5.6.9.2 Automatic Routines Arbitration
Priority and pending automatic routines
Each automatic subroutine has its assigned priority, according to Table
5-1 above.
When the conditions to the activation of two implemented automatic subroutines arise simultaneously the
automatic subroutine with the higher priority will be called.
The other automatic subroutine will be marked as pending. It will execute at the first time it has the
permission to execute – even if the reason for its call does not exist any more.
5.6.9.3 The Automatic Subroutine Mask
Automatic subroutines may be masked, i.e. set inactive. For example, it may be desired to limit the
automatic response to a certain digital input will be limited to certain situations.
This is done using the MI command.
Example:
An amplifier is commanded by a PLC. The Amplifier has an autoexec routine, which activates its program
upon boot. The PLC sends instructions to the Amplifier using RS232 communication for task parameters and
a digital input to start an action immediately . The A mplifier sets output according to the state of the program.
For safety, the Amplifier is not allowed to perform any task before digital input 2 is set:
function autoexec () **Declare the autoexec function
mi=8; **Inhibit the routine #@AUTO_I1
op=1; **Set output to indicate start.
….
while (!IB[2]) ** Wait for setting the digital input 2
end
goto #@TEST_PARS; **Jump to subroutine
##LOOP **Label LOOP
… **Label LOOP body
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
goto ##LOOP; **Endless loop
#@TEST_PARS **Subroutine
op=2; **Set output 2
wait 2000; **Wait 2 seconds for testing the part
mi=0; **Enable automatic handling of digital in #1
goto ##LOOP;
return **End of the autoexec function
#@AUTO_I1 **Automatic handler for digital input #1
op=3; **Set output 3 to indicate din 1 sensed.
**Subroutine body.
return **Subroutine end
…
exit **Exit from the program
The mask may also be used for preventing that switch bouncing will generate spurious routine calls
Example:
A machine performs a periodic task.
Digital input #1 is connected to a sensor to which the Amplifier should react.
The code below limits the automatic response to digital input #1during to executing the #@AUTO_I1
routine code, even though the digital input #1 may bounce.
##LOOP; **Repetitive task
…
MI=0; **Re-enable automatic routine
…
goto ##LOOP;
#@AUTO_I1 **Automatic handler for digital input #1
MI=MI|8; **Prevent nested calls to #@AUTO_I1
… **Subroutine body
return **Subroutine end
50
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
6 Program Development and Execution
The process of program development includes the following steps:
•
Program editing – Writing\editing the program.
•
Compilation – Let the Compiler process the program and find errors
•
Program loading – Load the program to the Amplifier Flash memory.
•
Debugging – Observe the program behavior, and correct where necessary
•
Running the program
•
Save to flash – Make the program reside permanently in the Amplifier.
6.1 Editing a Program
The Amplifier program is a simple text. Any text editor can be used to write the Amplifier program.
The Composer program has a development environment for Amplifier programs, which includes a program
editor. We recommend using the development environment of the Composer, since it provides several
services like downloading the program to the Amplifier, compiling the program and running it.
51
6.2 Compilation
Each user program after editing must be compiled.
The Compiler is described here, although id does not reside in the DSP software. The compiler is external
stand-alone software that may be called, for example by the Composer software. User can write and compile
program in the off-line mode (without communication establishing with Amplifier)
The Compiler compiles a program in order to produce address maps and run-time code. If in the course of
the compilation it finds syntax errors, it stops the compilation and informs the user about errors and presents
them in convenient form.
The compiler accepts the user program as text file and several files with Target Harm onica Information. This
information is required to assure that the produced compiled code can run on the Harmonica.
The Compiler outputs are two files:
CompileStat.txt file tells the compilation status. It reports success or failure and if the compilation failed
The
it tells what were the errors.
CompileCode.img exists only if compilation succeeded. It contains the compiled image file, to be
The
downloaded directly to the Harmonica. The description of the contents image file see at User Partition of the
Flash
The compiler catches syntax errors. It cannot catch:
•
Out of range command arguments
•
Bad command contexts like an attempt to begin a motion while the motor is off.
Such errors must be corrected in the debugging stage.
CompileStat.txt and CompileCode.img.
6.2.1 Compilation Error List
The list of the compilation errors is represented below:
Error
code
0 No errors Successful compilation without errors
1 Bad format This is general error for bad syntax at right or left hand expression.
Error string Meaning and example
For example,
for k = 1::10
There is double colon symbol between ‘1’ and ‘10’
b = a + ()
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
52
There is empty expression inside round brackets
k = 1:2:20
Colon expression is used out of ‘for’ statement
2 Empty expression Expected right hand expression is absent
For example,
a = ;
After assignment symbol the right hand expression is absent
3 Stack is full Stack overflows its depth
4 Bad index expression This error appears if an index expression of a variable is not evaluated in a
single value.
For example,
a(2,3)
The result of evaluation of the expression in round brackets is two values, not
a single value.
One more example,
a()
The index expression is empty
5 Bad variable type The expected variable type is neither ‘float’ nor ‘int’. This error may appear
either after the keyword ‘global’ or input/output arguments at the function
definition.
For example,
global floa a;
After the keyword ‘global’ the variable type is expected. The type ‘floa’ is
unknown.
function foo (long a)
In round parentheses the type of the input argument is expected. The type
‘long’ is unknown.
6 Parentheses mismatch The number of opening parentheses does not match to the number of closing
parentheses. It regards to as round as square parentheses.
For example,
b = a(1))
There is unnecessary closing parenthesis.
7 Value is expected This error appears if right or left hand expression is not evaluated in a single
value or it failed during evaluation of a bad syntax expression For example,
b = ^ a ;
Before operator ‘^’ a value is expected.
8 Operator is expected This error appears during right hand expression evaluation, if after successful
value evaluation there is neither operator nor terminator of a simple
expression.
For example,
b = a c ;
After successful evaluation of ‘a’ an operator or expression terminator is
expected, but ‘c’ is not recognized neither as an operator nor as a terminator.
9 Out of memory in the
data segment
This error appears during memory allocation for global variable: there is no
enough place at the data segment.
10 Bad colon expression Error during evaluation of colon expression. The colon expression may
appear only in ‘for’ statement.
Bad syntax of colon expression may cause to this error: more than three
values or less than two values in the colon expression.
For example,
for k = 10:-1:5:9
The colon expression contains more than tree values.
This error also appears if expected colon expression is absent at the ‘for’
statement.
for k = a
After the symbol ‘=’ colon expression is expected
Elmo HARmonica Software Manual
User program contains too many
functions and there no enough space for
HARSFEN0602
P R E L I M I N A R Y D R A F T
53
11 Name is too long Variable or function name exceeds 12 characters.
For example,
int iuyuafdsf_876234 ;
12 No such variable Left hand side error: left value is recognized neither as variable nor as system
command.
For example,
de = sin(0.5)
de is neither variable nor function.
13 Too many dimensions Dimension of array exceeds maximal admissible number of dimensions
(syntax allows only one dimensional arrays).
For example,
int arr[12][2];
It is attempt to define two dimensional array
14 Bad number of input
arguments
The number of input arguments during function call does not match to the
number of input arguments at the function definition.
For example,
function foo(float a); ** Function prototype
… ** Some code
foo(a,2); ** Function call
The number of input argument during function call is two, while the function
‘foo’ is defined with the only input argument.
15 Bad number of output
arguments
Bad syntax of left hand expression: multiple output without square brackets,
or multiple output exceeds maximal admissible number of outputs (it is
allowed maximal 16 outputs).
For example,
a, b = foo(1,2) ;
Multiple output must be within square brackets.
16 Out of memory Out of memory during compilation. This error may occur if user program is
too large or too complex and there is no enough space in the Code Segment
or Symbol Table.
17 Too many arguments The number of input or output arguments exceeds maximal admissible
number of input or output arguments (16).
For example,
function foo (int a1, int a2, int a3, int a4, int a5, int a6, int a7, int a8, int a9,
int a10, int a11, int a12, int a13, int a14, int a15, int a16, int a17, int a18, int
a19, int a20)
The number of input arguments exceeds 16.
18 Bad context It appears if the compiler finds any error that disorders a context of program.
For example, it may be mismatched parenthesis or improperly closed flow
control statement
19 Write file error Some error occurred during writing to a file.
20 Read file error Some error occurred during reading from a file
21 Internal compiler error:
bad database
It is internal compiler error because of corrupted database.
In a case of internal compiler error, please e-mail for technical support,
asusid@elmo.co.il
.
Please attach the Composer date and version (In the help menu in the toolbar)
and the program you tried to compile.
22 Function definition is
inside another function
or flow control block
Illegal function definition: inside another function or inside flow control
block.
For example,
if a < 0
a = 0 ;
function foo (int a);
end
Attempt to define function inside ‘if’ block.
23 Too many functions
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
them in the database
24 Name is keyword Variable or function name is the same as some keyword. This error may
appear if variable name is identical to some auto routine name.
For example,
int switch;
‘switch’ is keyword, so its use as variable name is illegal.
25 Name is not distinct This error occurs if some variable or function name is not distinct.
For example,
int foo ;
function foo (int a)
Function and variable have the same name ‘foo’,
One more example,
function foo (int a ) ** Function definition
int a ; ** Local variable definition
Definition of the local variable ‘a’ is illegal, because this function is already
contains local variable ‘a’ as input argument.
26 Variable name is
invalid
This error occur in the following cases:
1. Variable or function name starts from digit or underscore, but not
from letter
2. Variable or function name is empty
3. At the variable definition line there is a comma as a separator
between variables, but variable name after a comma is absent.
For example,
int _abc ;
function (int a)
int a, b,
In the first example variable name has leading underscore.
In the second example variable name is absent after a comma.
In the third example function name is absent after the keyword ‘function’.
27 Bad separator between
variables
The only legal separator between variables at the variable definition line is
comma. After variable name either variable separator (comma) or expression
terminator is expected. Any other symbol causes to this error.
For example,
int a b;
A command as variable separator is absent between ‘a’ and ‘b’.
28 Illegal global variable
definition
Global variable must be declared inside function with the keyword ‘global’
and must be defined before this function. This error appears only if the
keyword ‘global’ was used in the bad context:
1. The keyword ’global’ was used outside function.
2. Variable that is declared as global inside function is not defined
before.
3. Type of the variable at the definition outside the function differ from
the type of the declaration inside function
For example,
int a1 ; ** Global variable definition
function foo (int a) ** Function definition
global float a1; ** Declaration of the global variable inside function
Type of variable a1 at its definition is ‘int’, while inside function is declared
as ‘float’.
29 Bad variable definition All local variables must be defined at the beginning of the function. Any
variable definition after some executable code in the function is illegal.
For example,
function foo (int a) ** Function definition
int b ;
global int a1;
b = a ; ** Executable code
54
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
55
float c, d;
The definition of float variables ‘c’ and ‘d’ is illegal, because it occurs after
executable code ‘b = a’
30 Variable is undefined This error appears if iteration variable at ‘for’ statement is not defined before
it.
For example,
function foo (int a) ** Function definition
for k = 1 : 10 ** Start ‘for’ loop
a = k ;
end ** End ‘for’ loop
return ; ** Function end
The iteration variable ‘k’ is not defined before its use.
31 Bad separator between
dimensions
Bad separator between dimensions (not comma). This error is unused,
because currently it is allowed only one-dimensional arrays and no needs in
separator between dimensions.
32 Bad variable dimension Legal variable dimension must be a positive number inside square brack ets. I f
the expression inside square brackets is not evaluated into a number or this
number is less then one (zero or negative), it’s illegal.
For example,
int arr[-12];
Variable dimension is negative.
33 Bad function format This error appears at the function definition in the following cases:
1. Illegal function name – not distinct or empty, etc
2. Function definition does not match to its prototype
For example,
function foo (int a) ; ** Function prototype
function foo (float a) ** Function definition
Type of input arguments at the function definition and its prototype does not
match.
34 Illegal minus Minus is illegal in the following cases:
1. Minus before function call with multiple output arguments
2. Minus before round parentheses with multiple expressions inside it.
For example,
[a,b] = -foo(c) ;
-(2+3, c/5);
The first example has illegal minus before function call with multiple
outputs.
The second example has illegal minus before multiple expressions within
round parentheses.
35 Empty program User program is empty
36 Program is too long User program exceeds maximal admissible length
37 Bad function call The following reasons cause this error:
1. Attempt to jump at the ‘goto’ statement to the function with non zero
number of input or output arguments
2. Consider example:
[a,b,c] = foo(x,y) + 5;
This sentence is illegal.
The Compiler checks if there is an expression terminator straight after
function call with multiple outputs. Otherwise it sets this error.
38 Expression is expected This error appears when expected expression is absent. It may occur at ‘wait’,
‘until, ‘while’, ‘if’, ‘elseif’, ‘switch’ and ‘case’ statements.
For example,
if
a = 0
end
An expected expression after ‘if’ is absent.
Elmo HARmonica Software Manual
‘break’ is legal only inside ‘switch’, ‘for’ or ‘while’ bl
ock, otherwise, this
HARSFEN0602
P R E L I M I N A R Y D R A F T
39 Code is too complex User program contains very complex code that includes too many nested
levels (actually this expression contains more than 100 nested levels). Nested
expression means one flow control block inside other, e.g. ‘if’ block inside
‘while’ loop.
40 Line compilation is
General error during attempt to compile expression.
failed
41 Case must follow
switch
After ‘switch’ statement the only legal statement is ‘case’, otherwise this
error occurs.
For example,
switch a
b = 0 ;
case 1,
b =1 ;
end
The expression ‘b = 0’ is illegal, because ‘switch’ must be followed by
‘case’.
42 Illegal case after
otherwise
‘otherwise’ statement must be the last statem ent of ‘sw itch’ block . A ny ‘case’
after ‘otherwise’ is illegal.
For example,
switch a
case 1,
b =1 ;
otherwise
b = 0 ;
case 2,
b = 1 ;
end
The statement ‘case 2’ is illegal, because ‘otherwise’ must be the last
statement of ‘switch’.
43 Bad nesting This error treats flow control block contradictions: ‘else’ without ‘if’,
mismatched ‘end’, some flow control without ‘end’ etc.
44 Code is not expected This error occurs if there is some unexpected code for evaluation: after
‘otherwise’ or after ‘end’ or after ‘else’ etc.
45 Bad flow control
expression
This error occurs in ‘for’ statement if there is no a sign '=' after the iteration
variable name.
For example,
For k
a = 0 ;
end
After ‘k’ sign ‘=’ is absent.
46 Too many errors This error appears when buffer with compilation error is full.
47 Expression is out of
function
Some executable code must be inside either function or label, otherwise this
error occurs.
For example,
int a1; ** Global variable definition
a1 = 0 ; ** Executable code
function foo (int a) ** Function definition
Executable code is illegal, because it is out of function.
48 Otherwise without any
case
This error occurs if straight after ‘switch’ statement ‘otherwise’ appears.
For example,
switch a
otherwise
b = 0 ;
end
After ‘switch’ statement ‘case’ is expected, not ‘otherwise’.
49 Misplaced break
56
Elmo HARmonica Software Manual
Function already has
HARSFEN0602
P R E L I M I N A R Y D R A F T
57
error occurs.
For example,
if a < 0
break ;
end
‘break’ from ‘if’ statement is illegal.
50 Too many outputs This error appears when number actual output arguments during function call
exceeds the number of output arguments during function definition.
For example,
function [int b] = foo (int a) ** Function definition
… ** Function body
return ; ** Function end
…
[c,d] = foo(a) ; ** Function call
Function call is illegal, because number of outputs is two, while this function
is defined with a single output argument.
51 Line is too long This error occurs if user program contains too long line (more than 128
characters).
52 Clause is too long This error occurs if user program contains too long expression to evaluate
(more than 512 characters). This expression may take several lines of user
program text.
53 Cannot find end of
End of sentence not found within range
sentance
54 Open file failure Attempt to open non-existing file: file name or its path may be not correct.
55 Bad file name The full path file name is too long.
56 No such function After ‘goto’ and ‘reset’ statement must be auto routine, user function or label
name, otherwise this error appears.
57 Variable is array This error occurs during attempt to assign the entire array variable, not its
single member.
For example,
int arr[10] ; ** Global variable definition
##START ** Label definition
arr[1] = 0 ;
arr = 0;
The last expression is not legal: attempt to assign the whole array.
58 Variable is not array Attempt to assign a scalar variable according to an index, as an array
For example,
int a1 ; ** Global variable definition ( scalar)
##START ** Label definition
a1[1] = 0 ;
The last expression is not legal: attempt to assign a scalar variable according
to an index.
59 Mismatch between left
and right hand side
expressions
This error appears if the number of left values does not match to the number
of values in right hand side expression.
For example,
[a,b] = 12 + c ;
The number of left values is two, while the number of values after evaluation
of right hand expression is one.
60 Illegal local array Syntax does not allow to define local array. Array must be global.
For example,
function foo (int a) ** Function definition
int arr[10] ;
… ** Function body
return ; ** Function end
Local array is illegal
61
This error occurs if function has more than one body.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
body For example,
function foo (int a)
wait 2000
return ;
…
function foo (int a)
until a
end
This text is illegal, because the function ‘foo’ has multiple bodies.
62 Opcode is not
supported by the
This error occurs if the specified version of the Harmonica does not support
some virtual command.
Harmonica
63 Internal compiler error In a case of internal compiler error, please e-mail for technical support,
asusid@elmo.co.il
.
Please attach the Composer date and version (In the help menu in the toolbar)
and the program you tried to compile.
64 Expression is not
finished
User program contains unfinished sentence: user may use three points to
show that this expression will be continued at the next line. If this
continuation is absent, this error appears.
For example, assume that the last line of user text is:
a = b + 8 / 12 / (8^2*sqrt(2) – sin (3.14/2)) …
After three points the next line supposed to appear, but it is absent.
65 Compiled code is too
long
66 Corrupted the
The compiled code exceeds maximal allowable space for the Code Segment
in the serial flash of the Harmonica
Ant file with the Harmonica’s setup parameters does not have defined format.
Harmonica setup files
67 Too many variables User program contains too many functions and there no enough space for
them in the database
68 Variable name length
mismatch to the
Harmonica setup
69 Auto routine has
argument
The allowed variable name length is not equal to the defined length of the
Compiler
Auto routine cannot has any input or output argument, otherwise this error
appears.
For example,
function AUTOEXEC (int a)
Definition of auto routine with input argument is illegal.
70 Label definition is
inside flow control
Definition of label inside flow control block is illegal otherwise this error
appears.
block
71 Function without return Function has not finished with the keyword ‘return’
72 Block comments is not
finished
Comment block has no end.
For example, assume that it is the last line of user program text:
/* Stam comment
Comment block is not closed.
73 Bad function after reset In ‘reset’ statement must be either auto routine or global label or user
function without input arguments, otherwise this error appears.
For example,
reset foo(12)
After ‘reset’ keyword there is user function with input argument.
74 Bad jump to label This error appears in following cases:
1. Attempt to jump to global label from within some function or attempt
to jump to local label from within some global space
2. Attempt to jump to global label from within some function or attempt
to jump to local label from within some global space at ‘goto’
statement
3. Attempt to jump not to label at ‘goto’ label
58
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
4. Attempt to jump to local label at ‘reset’ statement
For example,
function foo () ** Function definition
… ** Function body
return ** Function end
…
goto ##foo
The last expression is illegal: foo is not label.
75 Illegal nargout The keyword ‘nargout’ is used outside function
For example,
##START ** Label
if nargout > 2
Use the keyword ‘nargout’ outside function
76 Function without body Attempt to call function which is defined but does not have body
77 Bad goto statement After the keyword ‘goto’ must be ## or #@ before the name of a label,
otherwise this error appears.
For example,
goto START
Between ‘goto’ and label name ## oe #@ is absent.
78 Auto routine is local Auto routine is defined as local label.
For example,
function start (int a) ** Function definition
… ** Some code
#@AUTOEXEC
…
return ** Function end
The auto routine AUTOEXEC is defined inside function as local label.
79 Command has 'not
program' flag
Program refers to command that has ‘not program’ falg, i.e. it cannot be used
inside user program.
For example,
LS
Attempt to use in a program the LS command that has ‘not program’ flag.
80 Image file is too long This error occurs if image file length exceeds user code partition size
81 System function tdif is
not supported by the
During evaluation of the wait flow control, the tdif system function is must
be defined inside the Harmonica, otherwise this error appears.
Harmonica
82 Unknown error Unknown error
59
6.3 Downloading and Uploading a Program
Note: In this step of the program development the communication between Composer and Harmonica must
be established.
After successful compilation the CompileCode.img
Composer’s development environment supports the downloading process. Before each download, Composer
automatically clears the memory Flash sector, which is used for saving the user program.
This section describes how the serial flash down/up loads.
The flash is interfaced using two commands:
DL and LS.
Both commands use the assisting command LP.
LP is a vector integer command.
The user flash area may be cleared by the command CP.
The user flash area may be checksum-verified, and program ready flag set, by the CC command.
may be downloaded to Harmonica.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
6.3.1 Binary data
The Flash is interfaced with binary data. Sending binary data on the RS232 lines is a problem, since they
complex the differentiation between data and delimiters.
The characters that are problematic to send on the RS232 lines are:
- All the high numbers, 128 to 255.
- All possible terminators: 0, <CR>, <LF>, ‘;’, ’,’
- Equating sign ‘=’
- Backspace
- Escape: <ESC>
In order to prevent this problem we use hex binary format during up/down load of data, even so it increases
amount of data to be transmitted.
Every byte in the hexadecimal form consists of two numbers (e.g. 0x12). The hex binary format consider
every of these two numbers as a character, e.g. the 8-bit number 0x12 in the hex binary format is the
sequence of two characters ‘1’,’2’.
Representation of numbers in the DSP Flash is different from its representation inside a personal computer.
A 8-bit number is represented in the same way as inside a personal computer.
Consider a 16-bit number. For example, the hexadecimal 16-bit number is equal to 0x1234. It is represented
in the DSP memory in the following two bytes:
Order number of the bytes Value of the byte in the hexadecimal form
1 0x12
2 0x34
Now consider 32-bit number. For example, the hexadecimal 32-bit number is equal to 0x12345678. It is
represented in the DSP memory in the following four bytes:
Order number of the bytes Value of the byte in the hexadecimal form
1 0x56
2 0x78
3 0x12
4 0x34
Binary data to be loaded to the serial flash is represented in the described above format.
Examples:
Number in the hexadecimal form
inside a personal computer
0x12 12
0x1234 1234
0x12345678 56781234
Sequence of characters in the hex binary form to be
transmitted
60
6.3.2 The Assisting Commands For Down/Upload
6.3.2.1 The LP[N] command
LP[1] defines the byte in which the next action is to start (out of 128k bytes of the flash)
LP[2] defines how many bytes to send (LS command).
The LP command is used together with the LS and the DL commands. Please refer the DL and the LS
explanations below.
In addition,
LP[3] specifies the start address (bytes) of the user program partition in the flash.
LP[4] specifies the size (bytes) of the user program partition in the flash
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
6.3.2.2 The CP command
The CP command clears the entire user area in the serial flash. It may take a significant time.
In special, CP sets the Program Valid flag to –1.
Possible Execution Failures:
1) Motor is on.
2) Program is running.
6.3.2.3 The CC command
The command CC=xxxx does as follows:
Read the actual length of the user partition from the TOC.
Calculate 32-bit checksum for the entire actual user partition.
The checksum shall be calculated by summing all the consecutive 2-bytes sequences (short int numbers) that
form the user program space and the checksum number itself. The total summing result must be zero to pass.
If the resulting checksum matches xxxx then:
•
Set the program ready flag.
•
Copy functions and variables symbol tables from the user partition to internal dsp flash memory
Else an error code is return.
CC returns 1 if the program ready flag in the serial flash is set
Otherwise it returns zero.
Possible Execution Failures:
1) Actual length in the TOC is less then 2 flash pages, or is beyond user program address limit.
2) Calculated checksum doesn’t match to xxxx.
61
6.3.3 Downloading a Program
6.3.3.1 The DL command
The Dl command executes downloading a program.
Downloading to a non-protected area in the Flash goes as follows:
LP[1]=start;
DL##xxxxxxxxx<ESC>CS;
where above xxxxxxxxx denotes the escape-sequenced data payload.
Start denotes the byte address in the user program flash.
CS denotes the 16 bits checksum for the message, including the DL##.
DL takes time, since it has to burn & verify.
Possible Execution Failures:
1) Attempt to write to protected area in the flash. It may happen that DL will start to write
legally to the Flash, but its last bytes will attempt an illegal (protected) write. In any case DL
command will be rejected, and the contents of the serial flash is unpredictable.
2) DL is used when motor is on.
3) DL is used when program is running.
4) Faulty checksum – DL will be rejected but creates no harm.
5) Verify error – If DL attempts to write to a previously written area in the flash, probably the
writing will fail by verify error. In that case the contents of the Flash is unpredictable and the
Flash has to be cleared and completely re-written.
6) DL string is too long. The maximum length of a DL string is 500 bytes, due to internal Dama
limits.
7) Program Valid flag is not –1. In that case DL comm and w ill not be executed (C P m ust be issued
before DL).
6.3.3.2 Program downloading process
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
In order to download a program image to the Dama, follow the steps below.
- Read the location (loc) and the length (len) of the user code partition from the
main TOC. For this, use the LP[3] and the LP[4] commands.
- Verify that your image block will fit inside the allocated space.
- Clear the program flash, using CP
- Download your image file by the sequence
•
LP[1]=loc;
•
DL##…100 bytes of payload
•
LP[1]=(loc+100)
•
DL##…next 100 bytes of payload
•
.. Until the end of the image
- Use the CC=checksum command to declare end of loading and to verify entire
download process.
In order to upload a program image from the Dama, follow the steps below.
- Read the location (loc) and the length (len) of the user code partition from the
main TOC. For this, use the LP[3] and the LP[4] commands.
- Upload your image file by the sequence
•
LP[1]=loc;
•
LP[2]=100
•
Use LS to get next 100 bytes of payload
•
LP[1]=(loc+100);
•
Use LS to get next 100 bytes of payload
•
.. Until the end of the image
62
6.3.4 Uploading a Program
6.3.4.1 The LS command
A program that resides in the Amplifier Flash can be uploaded for backup or for further editing. This option
is disable when program is running. After program uploading, user can correct it and returns to the
compilation step.
The LS command executes uploading a program.
Uploading from a non-protected area in the Flash goes as follows:
LP[1]=start;
LP[2]=payload net length
xxxxxxxxx<ESC>CS;
where above xxxxxxxxx denotes the escape-sequenced data payload.
Start denotes the byte address in the user program flash.
CS denotes the 16 bits checksum for the message.
Possible Execution Failures:
1) LS sequence (including <ESC>’s) exceeds 200 characters. The LS output will be terminated
with proper checksum and terminator. The data transmitted in the payload is good and meaningful,
only not to the expected length.
The 200 bytes limit is due to internal Dama buffer management.
6.4 The program execution
Note: In this step of Harmonica’s development we disable possibility to run more than one task, the virtual
machine, simultaneously. But in the future, this feature will be possible.
The following paragraphs describe how to run a program.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
6.4.1 Initiating a Program
A program is initiated by the XQ command. The XQ command states at which label the
execution shall start.
The XQ command resets all the prog ram variables. In particular, it clears the call stack (refer
the chapter the Functions and the Call Stack
), it kills any pending automatic routines, and it
clears the interrupt mask.
The description and syntax of the XQ command see at the chapter Debugging: running,
breaking and resuming
6.4.2 Halting and resuming a program
A program may be halted using the HP Interpreter command.
The HP command stops the execution of the user program and the automatic routines. The HP command
freezes the status of the program, and does not reset it.
A later XC command will resume the program from the instruction where the program was halted. Pending
interrupts will remain pending.
The command XC restarts execution from the point where the program has been halted.
Example:
Consider the program
MO=1; **Start motor
JV=2000; **Set jog speed
##LOOP; **Repetitive task
BG;
wait(1000) **Wait & switch direction
JV=-JV;
goto##LOOP; **Repeat
This program makes the motor travel at 2000 counts/sec for one second, then reverses the direction for one
second, continuing to travel back and forth forever.
Suppose the HP command is applied when the program waits (executing the wait(1000) instruction). The
motor will continue to travel at the same direction, for unlimited time.
An XC command shall reverse the direction immediately, since the waiting time already elapsed.
Example:
A servo axis in a machine has two different tasks to do, in two different machine modes.
The following routine implements the two tasks.
##TASK1;
##LOOP; **Repetitive task 1
… **Task 1 body
goto##LOOP; **Repeat task 1
##TASK2;
##REP; **Repetitive task 2
… **Task 2 body
goto##REP; **Repeat task 2
The first task is invoked by
XQ##TASK1
In order to switch to the second task, the first task has to be killed before:
63
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
HP;
XQ##TASK2;
6.4.3 Automatic program running with power up
If the user program includes the autoexec function, the next program line after function declaration will be
performed with powering up.
6.4.4 Save to Flash
Since a program is downloaded to a non-volatile memory, it is always saved. Information isn’t lost in cases
of power down.
6.4.4.1 Clear user program from Flash
The CP command clears the entire user area in the serial flash. The running program must be killed (not
halted) before.
This procedure may take a significant time.
64
6.5 Debugging
This method allows a debug the user program that is downloaded to the Harmonica’s flash. This may be
useful during development the user program and examination the program flow.
6.5.1 Running, breaking, and resuming
The XQ command starts program execution from a label, or executes a function.
XQ##MYFUNCTION(a,b,c) runs the function MYFUNCTION(a,b,c).
XQ cannot return values from a function.
XQ##LABEL runs from ##LABEL
XQ## runs from the starting of the user program code.
The XQ command without a parameter is illegal.
XQ does not return value.
Note: XQ## without label or function name is designed for running the program written in the
Saxophone/Clarinet style, i.e. without function definitions, local variables, etc. The virtual machine executes
virtual assembly commands according to their order in the compiled code. If the program contains function
definition, it enters inside function and executes function body. It is problematic, so we try to prevent it. If
the program starts from a function definition, the XQ command without label or function name causes to the
error: NO_SUCH_FUNCTION. If the function starts from label, the dummy start label w ill be inserted to the
function symbol table and running will be from the start of the program.
KL=0 kills all the virtual machines, if it is running.
KL stops the motor.
HP halts all the virtual machines. They can be continued later by the XC command.
If HP halts inside a wait statement, the wait time stops to run while the program is halted.
XC continues all the virtual machines.
6.5.2 DB command
The DB command is designed to help analyze the user program. It allows the following functionalities:
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
•
set and remove break points
•
get information about existing VAC machines
•
get running status of the program
•
ask for or change a value of local variables
•
get call stack of the program
The DB command is designed for the IDE Manager use. The syntax of this command is strict, namely the
spaces and white characters are not allowed to simplify the treatment of the command and all values must be
numbers, expressions are illegal.
6.5.3 Machine status
The command DB##MS returns status about all existing VAC machines.
Syntax:
DB##MS
The command DB##MS return a string in hex binary format containing 16-bit number. Every 4 bits
characterizes the status of the VAC machine, so the command can give a status of four VAC machines as
maximum. The returned status may get the following values:
0: Halted
1: Running
2: Idle/Not running
3: Aborted/Fault
4: Not existing
65
6.5.4 Program status
The command DB##PS returns the status of user program.
Syntax:
DB##PS[N]
where N is a handle of a specified VAC Machine.
The command DB##PS returns a string containing hex binary data with the following information:
Name Meaning Type of data Size in
bytes
1 Status Running status. See 6.4. signed short 2
2 Error
code
3 Program
counter
(PC)
4 Base
pointer
(BP)
5 Stack
pointer
(SP)
The non-zero error code indicates that any error occurred.
How to define which of VAC machine caused to an error?
The last error code or 0 for no error signed short 2
The program counter of the present executing
line
The current base pointer. The base pointer is
unsigned short
2
unsigned short 2
the saved stack pointer, which marks function
entry point.
BP is used to refer local variables of a
function.
The current stack pointer unsigned short 2
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
When any error occurs inside a specified VAC machine, it returns with error to the main loop that manages
the running of the entire set of VAC machines. This manager stops all other VAC machines with the error
ABORTED_BY_OTHER_THREAD. In order to define in which VAC machine the error occurred, find the
error code different from ABORTED_BY_OTHER_THREAD.
The DB##PS command returns information an analysis of which allows various debug functionality
described below.
6.5.5 Setting and clearing break points
Dama supports up to 6 breakpoints simultaneously. A user can set 5 breakpoints and one for inner use of the
IDE.
Breakpoints can be set anytime, anywhere, regardless if the program is running or not.
The syntax is
DB##BP=xxx
Sets a breakpoint at program counter xxx.
DB##BP=xxx,n
Sets a breakpoint at line program counter, activated only after n repetitions.
DB##BC=xxx
Removes a breakpoint at program counter
DB##BC
Removes all the breakpoints.
xxx is unsigned long – 4 bytes, n is signed short – 2 bytes.
66
6.5.6 Continuation of the program
When the program reaches the break point, it stops running of the entire set of existing virtual machines. To
cause the program to continue the running, the command DB##GO is used.
Syntax:
DB##GO
and
DB##GO[N]
where N is a handle of a specified VAC machine.
It continues the program running from the current program counter.
The DB##GO command continue running of all the VAC machines.
The DB##GO[N] command continue running of a specified VAC machine.
How to define a handle of a specified VAC machine, which was halted at the break point?
It must be found out the existing VAC machine whose program counter is equal to the program counter of
the break point. First the DB##MS command must be sent to define which VAC machines exist. After that
for all existing VAC machines we have to send the DB##PS command to get the program counter for
comparison with the break point program counter. It may occur the situation when several VAC machines
have the same program counter that is equal to the break point program counter. Every of them may be
chosen as a specified.
6.5.7 Single step
When a program reaches a break point, a user may desire to continue running in the single step mode.
6.5.7.1 Run to Cursor
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
The treatment of Run to Cursor is very easy: the IDE sets at the relevant line fake break point with the
number of repetitions as one. When a break point is reached, it has to be removed from the break point list.
There is no need to define special debug command.
6.5.7.2 Step Over
The DB##SO command executes the treatment of Step Over. It runs up to the nearest end of line.
Syntax:
DB##SO[N]
where N is a handle of a specified VAC machine.
This command is implemented inside the Harmonica. The algorithm is following:
•
Save the current base pointer
•
Start the loop
•
Run to the nearest end of line
•
Compare the current base pointer with the saved base pointer
•
If both of them are the same, the step is over - jump to the end the loop, otherwise go to
the start of the loop.
•
End of the loop
When the nearest end of line is reached, the VAC machine enters to the halted state. In case of jump or
infinite loop or other reason inside line execution, the program may not reach end of line, then it just runs
and does not enter halted state.
67
6.5.7.3 Step In
The DB##SI command executes the treatment of Step In. It enters inside function body and runs up to the
nearest end of line.
Syntax:
DB##SI[N]
where N is a handle of a specified VAC machine.
This command is implemented inside the Harmonica. The algorithm is following:
•
Start of the loop
•
Run to the nearest end of line
•
End of the loop
When the nearest end of line is reached, the VAC machine enters to the halted state.
6.5.7.4 Step Out
The DB##SU command executes the treatment of Step Out. It returns from function body and runs up to the
nearest end of line.
Syntax:
DB##SU[N]
where N is a handle of a specified VAC machine.
This command is implemented inside the Harmonica. The algorithm is following:
•
Save the current base pointer
•
Start of the loop
•
Run to the nearest end of line
•
Compare the current base pointer with the saved base pointer
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
•
If the current base pointer is less than the saved base pointer, the step is out - jump to the
end the loop, otherwise go to the start of the loop.
•
End of the loop
When the nearest end of line is reached and the current base pointer is less than the saved
base pointer, then the VAC machine enters to the halted state. Otherwise it just runs and
does not enter halted state.
6.5.8 Getting stack entries
The DB##GS command returns relevant entries of the stack.
Syntax:
DB##GS[N]=N1,N2
where N is a handle of a specified VAC machine whose stack is inquired,
N1 is an index of the first stack entry and
N2 is an index of the last stack entry (not including).
The command returns a string containing hex binary data with sequence of stack entries from N1 to N2.
If we are interested in the only stack entry, then N2 = N1 + 1.
The command returns a string in the hex binary format.
Every stack entry is a structure contains the next fields:
Name Meaning Type Size in
bytes
1 value Stack entry value float or long
depending on type
2 type Type of the stack entry: 0 for long,
signed short 2
1 for float
3 unused Offset for alignment signed short 2
This command is very useful during debugging.
4
68
6.5.9 Setting stack
The command DB##ST sets stack entry. This entry must be local variable or input/output argument of the
function.
Syntax:
DB##ST[N]=N1,N2
where N is a handle of a specified VAC machine (signed short –2 bytes),
N1 is stack pointer (signed short – 2 bytes) and
N2 is new variable value (long or float – 4 bytes)
A user may want to change a value of the local variable. The command DB##SS sets new value to the
relevant stack entry for a specified VAC machine.
The type of the stack entry will be set according to the type of the sent value.
6.5.10 Getting call stack
There is no direct command to get call stack. In order to reduce complexity of the
Dama, the IDE Manager will execute the all debug analysis.
Consider stack during function call (for more details see 8.2).
Stack pointer
relatively to the
base pointer
BP-5 Saved previous BP For the first called
Meaning Remark
function BP is 0
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
BP-4 Return address Program counter of the
next program line after
the function call
BP-3 Index of the current function in the Function
See 3.5.5
Symbol Table
BP-2 Number of input arguments
BP-1 Number of actual output arguments Number of left hand side
values during function
call
Let’s try to understand how this information can help us to restore call stack.
When the first function is called, its BP is zero. Every next function during its call saves the previous base
pointer in the stack at BP-5, so it can restore BP during return from the function. When we want to get the
entire call stack, we have to roll back the previous base pointer in the loop until BP becomes zero.
The algorithm to restore call stack is in the table below:
•
DB##PS[N] ; ** Get current status
•
Check the current status: if it not halted, return error.
•
BP_last = BP ; ** Get current BP from the data returned by DB##PS
•
N1 = 0 ; ** An index of the bottom of the stack
•
N2 = SP ; ** An index of the top of the stack
•
DB##GS=N1,N2; ** Get the entire stack
•
do **Start do-while loop until BP_last is not 0
•
funcIndex = BP_last – 3 ; ** Get called function index in the Sym bol Table **and insert
it to the call stack
•
if (BP_last == 0) break ; ** It is the first called function
•
BP_last = BP_last – 5 ; ** Update BP_last
•
while (1) ** End of do-while loop
69
6.5.11 View of global variables
The global variable may be accessed through the Interpreter. There is no need in the special debug
command.
6.5.12 View of local variables
Local variable cannot be accessed through the Interpreter. We don’t define special debug command to access
a local variable in order to prevent excessive complexity of the Dama. The IDE Manager can access a local
variable by using of existing debug commands and an analysis of their results as during getting call stack.
The algorithm is as follows:
•
DB##PS[N] ; ** Get current status
•
Check the current status: if it is not halted, return error.
•
DB##GS[N]=BP-3,BP-2; **Get an index of the function in the Function Symbol Table.
It is located in the stack at (BP – 3).
•
Search in the Variable Symbol Table for all local variables of this function. Variables in
the Symbol Table are sorted first according to an index of the function to whose they
belong and after that according to a variable name (case sensitive). The Symbol Table
contains full information about type and location of the variable (see 3.5.6).
•
To view a specified local variable use the DB##GS command.
•
To set new value of a specified local variable use the DB##ST command.
Note:
The allocation of place for local variables is executed by the command LINK. It inserts N entries to the
top of the stack and zeros them, where N is the number of local variables. Usually LINK is the first op
code of the function. It may occur that access to a local variable takes place before the op code LINK is
executed. In this case the relevant stack entries contains garbage.
The behavior of the debugger may be developed according to two scenarios:
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
1. Don’t analyze current state of the stack and just access to the relevant stack entries and get
garbage.
Try to analyze current program counter to find out whether the LINK was executed. If access to local
variable occurred before LINK, then return error (something like VARIABLE_NOT_INITIALIZED).
70
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
7 The Virtual Machines
7.1.1 Introduction Alla please complete where necessary
The Harmonica can run a user program, as explained in the Chapter "The Harmonica User Programming
Language". Although the user program runs syntactically the same statements as the interpreter, the
processing mechanism is totally different.
The interpreter analyses text on line. The user program does not – it runs a compiled code. The most
important advantage is that all the text analysis can be spared in real-time, boosting the user program
performance. Another advantage is that future user syntax improvements are possible without upgrading the
amplifier software.
An external tool, called "The Harmonica Compiler" compiles the user text. The compiler outputs a file of
short and simple binary commands.
Take for example the user text
DC=AC+1000;
This code is translated to
.... Alla please fill.
The texts of the compiled version above are in a mnemonic form. Each mnemonic represents an opcode of
fixed structure, as described below. In hexadecimal form, the example piece of code is
.... Alla please fill.
The compiled code looks much like an assembly language. The "CPU" that runs this assembly language is
written in DSP software. This software that implements the "User Program CPU" is called a "Virtual
Machine".
A virtual machine behaves much like a CPU – it has a stack, a code segment with program counter, and a
data memory segment.
The Harmonica is designed with multiple virtual machines, so that several user programs may be run in
parallel.
The machines are not completely similar. Only one machine, called the Main machine, is interrupted by
automatic routines. The other machines are not interrupted by automatic routines. If one desires to interrupt
another machine, he may write a software interrupt to that machine from the automatic routine handler of the
main machine.
The first release allows the user to activate only one (the Main) virtual machine.
71
7.2 Virtual Machine registers
A virtual machine has the following registers:
Register Description Comment
SP Stack pointer Points to top of stack.
BP Base pointer Freezes the value of the stack pointer
when a function is entered. BP is
used to refer local variables of a
function.
PC Program counter Points to the code position now
executing.
7.3 Call Stack During Function Call
Consider a call stack during a function call (the opcode is USRSUBJ).
Assume that a user defines a function :
function [float x, float y, float z] = f (int a, int b, int c, ind d) ; % Prototype
Assume that a function call is:
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
[x,y] = f (a,b,c,d) ;
Assume that BP before function call is 12 and SP is 15 (just number not better and not worse than every
other).
Before the opcode USRSUBJ is executed the stack contains:
2. n entries for actual output arguments (according to the function call, not prototype)
3. n entries for input arguments (a number of input arguments during function call must be the
same as in the prototype)
In our example the stack pointer before USRSUBJ is equal to 21:
is was 15 + 2 of actual output arguments + 4 of input arguments.
Now the opcode USRSUBJ is executing. During USRSUBJ execution stack is increased by 5 service entries
(from SP = 21 to SP = 25) and number of maximal output arguments according to the function definition.
The meaning of these service entries is described in the table below. The number of maximal possible output
arguments in our example is 3: x, y and z, from SP = 26 to SP = 28).
When 5 service entries has set to the stack a new value of BP is assigned (in our example 26), while the
previous value (12) is saved for later restoration.
This table below shows the contents of the stack for our example
SP Meaning Value Remark
12 BP before function call
…
15 Place for actual output argument y Junk SP before function call
16 Place for actual output argument x Junk
17 Input argument Value of a
18 Input argument Value of b
19 Input argument Value of c
20 Input argument Value of d
21 Save BP current 12 USRSUBJ start
22 Return address Value of return
address
23 Index of the function in the Function
Function index One of operands of
Symbol Table
One of operands of
USRSUBJ
USRSUBJ
24 Number of input arguments 4 Data from the Function
Symbol Table
25 Number of actual output arguments 2 One of operands of
USRSUBJ
26 Place for output argument x Junk New value of BP
27 Place for output argument y Junk
28 Place for output argument z Junk
29 USRSUBJ end.
…
After the opcode USRSUBJ ends SP is 29 and BP is 26.
During USRSUBJ the jump to the beginning of the function is executed (PC is assigned to the relevant
location in the Code Segment). Further filling of the stack is fulfilled according to the executable code of the
function.
Every function must end with return (the opcode USRSUBRT).
During USRSUBRT the stack returns to the initial state before function call, but not exactly.
USRSUBRT copies the actual output arguments to preliminary allocated place in the inverted order. In our
example z finally won’t be assigned, x will be copied from SP = 26 to SP = 16 and y will be copied from SP
= 27 to SP = 15.
BP is restored to the previous value (12). Service entries, input and output arguments are removed and
finally SP is 17.
72
7.4 Data types
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
The virtual machine supports the following data types:
- INTEGER: 32 BIT SIGNED INTEGER
- Float: 32 bit IEEE floating point number (24 bit mantissa, 8 bit sign)
Logical operators yield Boolean results – True or False.
True is equivalent to the integer 1.
False is equivalent to the integer 0.
7.5 Op code structure and addressing modes
Op code it’s a bit filed (16 bits) which give us information about the VAC (Virtual Assembly Code) and it’s
operands, more details in table below.
Each operand has an addressing mode indicates the location of the operand (stack, data seg ment, immediate).
Op code bit field:
Bits Description Meaning
0 ChangeStack Flag shows whether SP should change (increase/decrease) after
an execution of a VAC. This flag is ignored by some of the
commands. 1 – change stack, 0 – don’t change.
1-7 CodeIndex Index of VAC in table
8 OperType1 Data type of first operand . 1 – Float, 0 – Integer
9 OperType2 Data type of second operand
10-12 AddrMode1 Addressing mode of first operand (destination)
12-15 AddrMode2 Addressing mode of second operand (source)
Addressing Modes:
Addressing Mode
73
MEANING
ABSENT Lack operand after command code. Usually Operand is at
the top of stack.
IMMEDIATE1 Operand is char integer and stated immediately after
command code
IMMEDIATE2 Operand is short integer and stated immediately after
command code
IMMEDIATE4 Operand is long integer or float and stated immediately
after command code
MEM_DIRECT Operand is at the memory address (ram) which stated after
command code.
STACK_IMMEDIATELY Operand stated at stack member which placed after
command
BP_RELATIVE Operand is placed in the stack relatively to the base
pointer. Exact location in the stack is base pointer +
operand stated after command code.
7.6 Short reference
A concise reference is given in the table below.
OP code Meaning
MLT Multiply the top of stack with the number below.
SUB Subtract the top of stack from the number below.
ADD Add the top of stack to the number below.
DIV Divide the number below top of stack by the top of stack.
Elmo HARmonica Software Manual
Call to function service of a ‘set’
command whose index in the
HARSFEN0602
P R E L I M I N A R Y D R A F T
REM Reminder from division of the number below top of stack by the top
of stack.
RSLTAND Check if number at top of stack and number below are non zero than
condition is true otherwise condition is false
RSLTOR Check if number at top of stack or number below are non zero than
condition is true otherwise condition is false
XOR Bitwise XOR operator – between the number at top of stack and the
number below
NOT Bitwise NOT operator – on the number at the top of stack
SHR Logical right shift the number at the top of stack by the number below
top of stack
SHL Logical left shift the number at the top of stack by the number below
top of stack
AND Bitwise AND operator – between the number at top of stack and the
number below
F_OR Bitwise OR operator – between the number at top of stack and the
number below
UNARY_NOT Check if number at top of stack is non zero than condition is false
otherwise condition is true
RSLTE Compare the number at top of stack with the number below, if they
are equal condition is true
RSLTA Compare the number at top of stack with the number below, if
the first number is bigger condition is true
RSLTAE Compare the number at top of stack with the number below, if
the first number is bigger or they are equal condition is true
RSLTB Compare the number at top of stack with the number below, if
the first number is smaller condition is true
RSLTBE Compare the number at top of stack with the number below, if
the first number is smaller or equal condition is true
RSLTNE Compare the number at top of stack with the number below, if
they are not equal condition is true
MOV Assignment operator (=) between global/local variables, assign value
can also be constant
CMP Compare two values (they can be global/local variables, constants or
from stack), if they are equal condition is true
JMP Jump to different location in program
JMP_EOL Jump to different location in program, and force end of line (stop
execution of current program line until next cycle).
JMP_LABEL Jump to a label
JNZ Jump if value is not zero (tested value can be local/global variable or
constant)
JNZ_EOL Jump if value is not zero (tested value can be local/global variable or
constant) and force end of line (stop execution of current program line
until next cycle).
JZ Jump if value is zero (tested value can be local/global variable,
constant or from stack)
JZ_EOL Jump if value is zero (tested value can be local/global variable,
constant or from stack) and force end of line (stop execution of
current program line until next cycle).
SPADD Increase or decrease stack pointer with the value given as an argument
GETINDX Get value from array variable defined in data segment (array member
index is at top of stack)
SETINDX Set value to array variable defined in data segment (array member
index is at top of stack)
SET_COMM
74
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
function table is given as an argument
GET_COMM Call to function service of a ‘get’ command whose index in the
function table is given as an argument
SYSSUBJ Call to system function whose index in function table is given as
an argument
USRSUBJ Call to user subroutine whose index in the symbol function table is
given as an argument (push relevant function data to stack)
USRSUBRT Return from user subroutine – restore stack to its state before function
call, save output arguments in stack and jump to return address
FORITR Handle FOR loop – check condition, if true iterate and execute loop
body. Otherwise, break loop and continue program
EOL Indicate this is end of line
FREEVAC Stop program execution
LINK Increase stack pointer with the value given as an argument and zeroes
the new entries to stack
JMP_LABEL Unconditional jump to the label (entry point)
Table 7-1 – Harmonica op codes
7.7 Alphabetic reference
75
This section details the Harmonica virtual assembly commands.
7.7.1 ADD - ADDITION
Purpose:
Addition of two numbers (top two entries at the stack) .
Algorithm:
→
(SP-1) + (SP)
SP
→
SP-1
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
Addressing modes Absent
Promotion Int + Float
Output type Int + int → int
Imposes end of line No
(SP-1)
Executes as
(float) Int + Float
Int + Float
Float + Float
→
Float
→
Float
versions
according to stack members
flags
7.7.2 AND – Bitwise AND Operator
Purpose:
Bitwise AND operator – top two entries at the stack.
Algorithm:
(SP-1) & (SP)
→
SP - 1
SP
→
(SP-1)
Elmo HARmonica Software Manual
according to stack members
HARSFEN0602
P R E L I M I N A R Y D R A F T
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments None
Argument types N.A. Both arguments types must
be integer (set according to
stack members flags)
Addressing modes Absent
Promotion N.A.
Output type Int & Int → Int
Imposes end of line No
7.7.3 CMP – Compare
Purpose:
Compare two values (they can be global/local variables, constants or from stack), if they are equal condition
is true otherwise it is false.
Algorithm:
→
(Op1 == Op2 )
→
SP + 1
SP
Attributes:
Attribute Value Comment
Op code May change in future
Number of arguments 2
Argument type1 Int or Float If argument is from stack,
Argument type2 Int or Float
Addressing mode1 Absent , Immediate, Mem_Direct ,
Addressing mode2 Absent , Immediate, Mem_Direct ,
Promotion N.A.
Output type Int Compare result is always
Imposes end of line No
(SP)
versions
type is set according to stack
member flag
Stack Immediate, BP_Relative
Stack Immediate, BP_Relative
integer
76
7.7.4 DIV – Divide
Purpose:
Division of two numbers (top two entries at the stack).
Algorithm:
(SP-1) / (SP)
SP
→
SP-1
Attributes:
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
→
(SP-1)
versions
Elmo HARmonica Software Manual
Jump address to the end of
HARSFEN0602
P R E L I M I N A R Y D R A F T
flags
Addressing modes Absent
Promotion Int / Float
Executes as
(float) Int / Float
Output type Int / Int → Int
Int / Float
→
Float / Float
Float
→
Float
Imposes end of line No
7.7.5 EOL – End Of Line
Purpose:
Indicate this is end of line to the
Algorithm:
Zeroes line execution flag.
Attributes:
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A.
Addressing modes N.A.
Promotion N.A.
Output type N.A.
Imposes end of line No
Harmonica environment.
versions
77
7.7.6 FORITR – FOR Loop Iteration
Purpose:
Handle FOR loop – check condition, if true update iterator and execute loop body otherwise break loop and
continue program.
Algorithm:
itr – (iterator)
(SP-2)
(SP-1)
(SP)
if (step > 0)
if (itr > target) free top three entries at the stack and jump end of loop
else if (step < 0)
if (itr < target) free top three entries at the stack and jump end of loop
else
error (step = 0 , meaning infinite loop)
(SP-2) + step
(PC is incremented and loop body is executed)
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments 2
Argument Type1 Signed short integer
Argument Type2 Signed short integer
Addressing mode1 Immediate2
→
itr (set iterator with start value)
→
step
→
target (final value, to which itr is tested)
→
(SP-2) ( increment iterator by step)
versions
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
loop
Addressing mode2 Mem_Direct , BP_Relative Iterator variable address,
depend on the addressing
mode.
Promotion N.A.
Output type N.A.
Imposes end of line Only if jump address is out
of the present executing line.
7.7.7 FREE_VAC - Free Virtual Machine
Purpose:
Stop program execution.
Algorithm:
Zeroes program execution flag.
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments None
Argument types N.A.
Addressing modes N.A.
Promotion N.A.
Output type N.A.
Imposes end of line No
78
7.7.8 F_OR – Bitwise OR Operator
Purpose:
Bitwise OR operator – top two entries at the stack.
Algorithm:
(SP-1) | (SP)
→
SP-1
SP
→
(SP-1)
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments None
Argument types N.A. Both arguments types must
be integer (set according to
stack members flags)
Addressing modes Absent
Promotion N.A.
Output type Int | Int → Int
Imposes end of line No
7.7.9 GETINDEX
Purpose:
Get value from array variable defined in data segment.
Algorithm:
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
DataSeg + Op1 → Arr (array address)
→
(SP)
Arr[Ind]
Ind (array index)
→
(SP) (return value)
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 1
Argument type Signed short integer
Addressing modes Mem_Direct Location of variable (index)
in the variable symbol table.
Address of array variable is
taken from the table.
Array index is at top of stack.
Promotion N.A.
Output type Argument Type1 Value from array is pushed at
the top of stack instead of
array index
Imposes end of line No
79
7.7.10 GET_COMM – Get Command
Purpose:
Call to function service of a ‘get’ command.
Algorithm:
FuncTable
FuncTable[Op1]()
→
SP
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments 1
Argument types Unsigned char integer
Addressing modes Immediate1 Index of service function in
Promotion N.A.
Output type N.A. Output argument is at top of
Imposes end of line No
→
SP +1
(list of functions handlers)
→
(SP) (put return value at top of stack)
versions
function table.
If system parameter is an
array , array index is at top of
stack .
stack.
Type set according to service
function .
7.7.11 JMP – Jump
Purpose:
Jump to another location in the program.
Algorithm:
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
PC→ Immediate value
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 1
Argument type Signed short integer Jump Address
Addressing modes Immediate2
Promotion N.A.
Output type N.A.
Imposes end of line Only if jump address is out
of the present executing line.
7.7.12 JMP_EOL – Jump
Purpose:
Jump to another location in the program and force end of line . This is used in cases when we want to set
breakpoints at specific address but we cant because its not at new line.
Algorithm:
PC
→
Immediate value
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 1
Argument type Signed short integer Jump Address
Addressing modes Immediate2
Promotion N.A.
Output type N.A.
Imposes end of line Only if jump address is out
of the present executing line.
80
7.7.13 JMP_LABEL – Jump to the label
Purpose:
Jump to another location in the program.
Algorithm:
→
Immediate value
PC
Remarks:
The JMP_LABEL is similar to the opcode JMP. The only difference between them is in the argument. The
argument of JMP_LABEL contains the absolute jump address in the Code Segment, while the argument of
JMP is relative regards to the current location of the command pointer.
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 1
Argument type Unsigned short integer Label Address in the Code
Segment
Addressing modes Immediate2
Elmo HARmonica Software Manual
Only if jump add
ress is out of
HARSFEN0602
P R E L I M I N A R Y D R A F T
Promotion N.A.
Output type N.A.
Imposes end of line Only if jump address is out of
the present executing line.
7.7.14 JNZ – Jump Not Zero
Purpose:
Jump to if value is not zero (change PC to different location in program).
Algorithm:
PC → IMMEDIATE VALUE
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 2
Argument type1 Unsigned short integer Jump Address
Argument type2 Int or Float Tested value
Addressing mode1 Immediate2
Addressing mode2 Absent , Immediate,
Stack_Immediate,Mem_Direct,
BP_Relative
Promotion N.A.
Output type N.A.
Imposes end of line Only if jump address is out of
the present executing line.
(tested value can be
local/global variable or
constant)
81
7.7.15 JNZ_EOL – Jump Not Zero
Purpose:
Jump to if value is not zero (change PC to different location in program) and force end of line to allow
breakpoints in after jump instruction.
Algorithm:
PC → IMMEDIATE VALUE
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 2
Argument type1 Unsigned short integer Jump Address
Argument type2 Int or Float Tested value
Addressing mode1 Immediate2
Addressing mode2 Absent , Immediate,
Stack_Immediate,Mem_Direct,
BP_Relative
Promotion N.A.
Output type N.A.
Imposes end of line
(tested value can be
local/global variable or
constant)
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
the present executing line.
7.7.16 JZ – Jump If Zero
Purpose:
Jump to if value is zero (change PC to different location in program).
Algorithm:
PC → IMMEDIATE VALUE
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 2
Argument type1 Unsigned short integer Jump Address
Argument type2 Int or Float Tested value
Addressing mode1 Immediate2
Addressing mode2 Absent, Immediate,
Stack_Immediate,Mem_Direct,
BP_Relative
Promotion N.A.
Output type N.A.
Imposes end of line Only if jump address is out of
the present executing line.
(tested value can be
local/global variable or
constant)
82
7.7.17 JZ_EOL – Jump If Zero
Purpose:
Jump to if value is zero (change PC to different location in program) and force end of line to allow
breakpoints in after jump instruction.
Algorithm:
PC → IMMEDIATE VALUE
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 2
Argument type1 Unsigned short integer Jump Address
Argument type2 Int or Float Tested value
Addressing mode1 Immediate2
Addressing mode2 Absent, Immediate,
Stack_Immediate,Mem_Direct,
BP_Relative
Promotion N.A.
Output type N.A.
Imposes end of line Only if jump address is out of
the present executing line.
(tested value can be
local/global variable or
constant)
7.7.18 LINK
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Purpose:
Increase stack pointer with the value given as an argument and zeroes the new entries to stack.
Algorithm:
SP → SP + OP1
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 1
Argument type Unsigned char integer
Addressing modes Immediate1 Number of new entries to
stack
Promotion N.A.
Output type N.A.
Imposes end of line No
83
7.7.19 MLT – Multiply
Purpose:
Multiply two numbers (top two entries at the stack).
Algorithm:
(SP) * (SP-1)
SP
→
SP-1
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
Addressing modes Absent
Promotion Int * Float
Output type Int * int → int
Imposes end of line No
→
(SP-1)
Executes as
(float) Int * Float
Int * Float
Float * Float
→
Float
→
Float
versions
according to stack members
flags
7.7.20 MOV – Assignment Operator (=)
Purpose:
Assignment operator (=) between global/local variables, assign value can also be constant or value from
stack.
Algorithm:
OP1 → OP2
Elmo HARmonica Software Manual
be integer (set according to
HARSFEN0602
P R E L I M I N A R Y D R A F T
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 2
Argument type1 Int or Float If argument is from stack,
type is set according to stack
member flag
Argument type2 Int or Float
Addressing mode1 Absent, Immediate, Mem_Direct ,
Assigned value (source)
Stack_Immediate, BP_Relative
Addressing mode2 Absent, Mem_Direct ,
Stack_Immediate , BP_Relative
Variable or stack member
(Destination)
Promotion N.A.
Output type N.A.
Imposes end of line No
7.7.21 NOT – Bitwise NOT Operator
84
Purpose:
Bitwise NOT operator – number is at top of stack .
Algorithm:
~(SP)
→
(SP)
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments None
Argument types N.A. Argument type must be
integer (set according to
stack member flag)
Addressing modes Absent
Promotion N.A.
Output type ~Int → Int
Imposes end of line No
7.7.22 REM – Reminder
Purpose:
Reminder from division of two numbers (top two entries at the stack) .
Algorithm:
→
(SP-1) % (SP)
→
SP-1
SP
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types must
(SP-1)
versions
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
stack members flags)
Addressing modes Absent
Promotion N.A.
Output type Int % Int → Int
Imposes end of line No
7.7.23 RSLTA – Relational Operator (>)
Purpose:
Compare two numbers, if the first number is bigger condition is true otherwise it’s false (numbers are at top
two entries of the stack) .
Algorithm:
((SP-1) > (SP))
→
SP - 1
SP
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
Addressing modes Absent
Promotion N.A.
Output type Int Compare result is always
Imposes end of line No
→
(SP)
versions
according to stack members
flags
integer
85
7.7.24 RSLTAE – Relational Operator (>=)
Purpose:
Compare two numbers, if first number is bigger or they are equal condition is true otherwise it’s false
(numbers are at top two entries of the stack) .
Algorithm:
→
((SP-1) >= (SP))
→
SP - 1
SP
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
Addressing modes Absent
Promotion N.A.
Output type Int Compare result is always
Imposes end of line No
(SP)
versions
according to stack members
flags
integer
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
7.7.25 RSLTAND – Logical AND Operator (&&)
Purpose:
If both numbers are non-zero condition is true. Otherwise it is false (numbers are at top two entries of the
stack).
Algorithm:
(SP-1) && (SP)
SP
→
SP – 1
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types must
Addressing modes Absent
Promotion N.A.
Output type Int && Int → Int
Imposes end of line No
→
(SP-1)
versions
be integer (set according to
stack members flags)
86
7.7.26 RSLTB – Relational Operator (<)
Purpose:
Compare two numbers, if the first number is smaller condition is true otherwise it’s false (numbers are at top
two entries of the stack) .
Algorithm:
((SP-1) < (SP))
SP
→
SP - 1
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
Addressing modes Absent
Promotion N.A.
Output type Int Compare result is always
Imposes end of line No
→
(SP)
versions
according to stack members
flags
integer
7.7.27 RSLTBE – Relational Operator (<=)
Purpose:
Compare two numbers, if the first number is smaller or they are equal condition is true otherwise it’s false
(numbers are at top two entries of the stack) .
Algorithm:
((SP-1) <= (SP))
SP
→
SP - 1
Attributes
→
(SP)
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Attribute Value Comment
Op code May change in future
versions
Number of arguments None
Argument types N.A. Both arguments types are set
according to stack members
flags
Addressing modes Absent
Promotion N.A.
Output type Int Compare result is always
integer
Imposes end of line No
7.7.28 RSLTE – Relational Operator (==)
Purpose:
Compare two numbers, if they are equal condition is true otherwise its false (numbers are at top two entries
of the stack) .
Algorithm:
→
((SP-1) = = (SP))
→
SP - 1
SP
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
Addressing modes Absent
Promotion N.A.
Output type Int Compare result is always
Imposes end of line No
(SP)
versions
according to stack members
flags
integer
87
7.7.29 RSLTNE – Relational Operator (!=)
Purpose:
Compare two numbers, if they are not equal condition is true otherwise its false (numbers are at top two
entries of the stack) .
Algorithm:
((SP-1) != (SP))
SP
→
SP - 1
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
→
(SP)
versions
according to stack members
flags
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Addressing modes Absent
Promotion N.A.
Output type Int Compare result is always
integer
Imposes end of line No
7.7.30 RSLTOR – Logical OR Operator ( || )
Purpose:
If one of the numbers or both are non-zero condition is true otherwise it’s false (numbers are at top two
entries of the stack).
Algorithm:
(SP-1) || (SP)
SP
→
SP – 1
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types must
Addressing modes Absent
Promotion N.A.
Output type Int || Int → Int
Imposes end of line No
→
(SP-1)
versions
be integer (set according to
stack members flags)
88
7.7.31 SET_COMM – Set Command
Purpose:
Call to function service of a ‘set’ command.
Algorithm:
→
FuncTable
→
(SP)
(SP-1) → VAL
FuncTable[Op1](val , ArrayIndex) (call to ‘set’ command)
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments 1
Argument types Unsigned char integer
Addressing modes Immediate1 Index of service function in
Promotion N.A.
Output type N.A.
(list of functions handlers)
ArrayIndex
versions
function table.
Array index is at top of stack
.
Set value is at one entry
below top of stack.
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Imposes end of line No
7.7.32 SETINDEX
Purpose:
Set value to array variable defined in data segment.
Algorithm:
DataSeg + Op1
→
(SP)
(SP –1)
Ind (array index)
→
Arr[Ind] = val ; (enter value to array)
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments 1
Argument type Signed short integer
Addressing modes Mem_Direct Address of array in data
Promotion N.A.
Output type N.A. Type of assign value from
Imposes end of line No
→
Arr (array address)
Val (assign value)
versions
segment (ram) .
Array index is at top of stack
.
Set value is at one entry
below top of stack .
stack
89
7.7.33 SHR – Shift Right
Purpose:
Shift right the number below top of stack by the number at the top of stack.
Algorithm:
→
(SP-1) >> (SP)
→
SP – 1
SP
(SP-1)
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments None
Argument types N.A. Both arguments types must
be integer (set according to
stack members flags)
Addressing modes Absent
Promotion N.A.
Output type Int >> Int → Int
Imposes end of line No
7.7.34 SHL – Shift Left
Purpose:
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Shift left the number below top of stack by the number at the top of stack.
Algorithm:
(SP-1) << (SP)
SP
→
SP – 1
→
(SP-1)
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments None
Argument types N.A. Both arguments types must
be integer (set according to
stack members flags)
Addressing modes Absent
Promotion N.A.
Output type Int << Int → Int
Imposes end of line No
7.7.35 SPADD
90
Purpose:
Increase or decrease stack pointer with the value given as an argument.
Algorithm:
SP → SP + OP1
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 1
Argument type Signed char integer
Addressing modes Immediate1
Promotion N.A.
Output type N.A.
Imposes end of line No
7.7.36 SUB - SUBTRACT
Purpose:
Subtraction of two numbers (top two entries at the stack) .
Algorithm:
(SP-1) - (SP)
SP
→
SP-1
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types are set
→
(SP-1)
versions
according to stack members
flags
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Addressing modes Absent
Promotion Int - Float
Executes as
(float) Int - Float
Output type Int - int → int
Int - Float
→
Float - Float
Float
→
Float
Imposes end of line No
7.7.37 SYSSUBJ – Jump To System Subroutine
Purpose:
Call to system function.
Algorithm:
FuncTable
FuncTable[Op1]()
→
SP
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments 1
Argument types Unsigned char integer
Addressing modes Immediate1 Index of system function in
Promotion N.A.
Output type N.A. Output argument is at top of
Imposes end of line No
→
SP +1
(list of functions handlers)
→
(SP) (put return value at top of stack)
versions
function table
stack.
Type set according to service
function .
91
7.7.38 UNARY_NOT - Logical NOT Operator (!)
Purpose:
If number is non-zero condition is false otherwise condition is true.
Algorithm:
→
! (SP)
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Argument type must be
Addressing modes Absent
Promotion N.A.
Output type !Int → Int
Imposes end of line No
(SP)
versions
integer (set according to
stack member flag)
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
7.7.39 USRSUBJ – jump To User Subroutine
Purpose:
Call to user subroutine (push relevant function data to stack).
SEE 8.2
Algorithm:
→
(SP) (save base pointer)
BP
→
SP + 1
SP
OP2
→
(SP) (save return address)
SP
→
SP + 1
→
FuncIndex
SP
→
SP + 1
NArgIn
(SP) (save function index)
→
(SP) (save number of input arguments)
92
7.7.39.1.1.1.1.1 SP
→
SP + 1
NActArgOut → (SP) (save number of actual output arguments)
SP
→
SP + 1
→
BP (update base pointer)
SP
PC
→
FuncAddr (jump to user subroutine)
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments 2
Argument type1 Unsigned short integer Lower 8 bits :
Actual ouput arguments
Upper 8 bits :
Subroutine Index
Argument type1 Unsigned short integer Return Address
Addressing mode1 Immediate2
Addressing mode1 Immediate2
Promotion N.A.
Output type N.A.
Imposes end of line Yes jump address is out of the
present executing line.
7.7.40 USRSUBRT – Return from user subroutine
Purpose:
Return from user subroutine - restore stack to its state before function call, save output arguments in stack
and jump to return address.
See 8.2
Algorithm:
7.7.40.1.1.1.1.1 (SP-1)
(SP-2) → nArgIn (num of input arguments)
→
(SP-4)
SP
RtAddr (return address)
→
BP – 5 - nArgIn
(save output arguments from subroutine)
→
(SP-5)
PC
BP (base pointer)
→
RtAddr (return from user subroutine)
→
nActArgOut (number of actual output arguments)
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Attributes
Attribute Value Comment
Op code May change in future
versions
Number of arguments None
Argument types N.A.
Addressing modes N.A.
Promotion N.A.
Output type N.A.
Imposes end of line Yes Jump address is out of the
present executing line.
7.7.41 XOR – Bitwise XOR Operator
Purpose:
Bitwise XOR operator – top two entries at the stack.
Algorithm:
(SP-1) ^ (SP)
SP
→
SP-1
Attributes
Attribute Value Comment
Op code May change in future
Number of arguments None
Argument types N.A. Both arguments types must
Addressing modes Absent
Promotion N.A.
Output type Int ^ Int → Int
Imposes end of line No
→
(SP-1)
versions
be integer (set according to
stack members flags)
93
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
8 The Recorder
The recorder mechanism enables the user to record various signals that exist in the
Harmonica, up to 8 signals simultaneously. The recorded signals can be uploaded to the host
by communication, for the purpose of presentation and analysis.
The following section details how to define the recorder parameters to the Harmonica, how
to launch and trigger the recorder, and how to fetch the recorded data.
The average user does not have to know all this detail, since the Composer program
normally operate the recorder with a user-friendly interface.
The list of record-able signals supported by a Harmonica is stored internally and can be
retrieved by the host. Please refer to LS and LP commands in the Software Manual.
The following commands are relevant for the recording process.
Command Description
BG,BT,
IL[N]
BH Upload recorder results.
LS Load a record from the serial flash.
RC Defines which of the mapped signals shall be recorded.
RG Recorder gap. Specify the sampling rate of the recorder.
RL Recorder length.
RP[N] Recorder parameters.
RR Launch the recorder, and read back its status
RV Signal mapping.
SR Status register – tells the status of the recorder – idle, armed, triggered and recording,
TS Sampling time the basic resolution of the recorder.
WI[21] The actual amount of recorded data.
Begin motion by software or hardware command. Motion beginning may be used to
trigger the recorder.
Use in order to retrieve the list of recorder signals
This command defines what event will trigger the recorder, and the trigger position.
It also defines:
- The basic time quantum for the recorder is TS or four times TS.
- The data to be uploaded to the host by the next BH command.
This command maps the ID's of the record able signals to logical ID's that the recorder
can refer.
or ready with data.
94
Table 8-1: Commands relevant to the recorder
8.1 Recorder sequencing: Programming, launching, and uploading data.
In order to activate the recorder, it must be programmed. Programming the recorder means
telling the recorder what signals to record, at what resolution, and what shall be the trigger
event.
Few limitations apply:
- The recorder cannot be programmed while it is armed, or recording. It has to be
killed first (RR=-1).
- Changing the recorder programming invalidates any previously recorded data.
Be sure to upload all the data you need before programming the recorder.
After programming, the recorder can be launched by:
- RR=1 will arm the recorder to trigger at the next motion begin (obsolete, please
use RR=3)
- RR=2 will start recording immediately.
- RR=3 will arm the recorder to start recording at the next trigger event.
The status of the recorder may be polled using the RR and SR commands.
After the recorder data is ready, use the BH command to upload the data.
Elmo HARmonica Software Manual
Long
– The position counter, counted modulo a mechanical
HARSFEN0602
P R E L I M I N A R Y D R A F T
8.2 Signal mapping
The recorder can record many different signals.
The first 16 signals that may be recorded are compatible with older amplifiers. They are
listed is in the table below.
Signal
ID
1 Main Speed (VX) Long –
2 Main Position (PX) Long –
3 Position Command (DV[3]) Long –
4 Digital input pins status Short
5 Position Error (PE) Long -
6 Current Command (DV[1]) Short –
7 DC Bus Voltage Short –
8 Auxiliary Position (PY) Long –
9 Auxiliary Speed (VY) Long –
10 Active current command
11 Reactive current command
12 Analog Input 1 (AN[1]) Short –
13 Reserved
14 Motor current phase A
15 Motor current phase B
16 Speed Command (DV[2]) Long –
Signal Name (Command) Length –
Type
Float
Integer
Integer
integer
Integer
Float
Integer
Integer
Float
Short –
(IQ)
Float
Short –
(ID)
Float
Float
Short –
(AN[3])
Float
Short –
(AN[4])
Float
Float
Description
Speed of main feedback sensor in counts/sec
Position accumulation of the main feedback sensor
in counts
Position reference in counts. When external
reference mode is set (RM=1) this signals includes
also the analog reference command.
The IP variable (refer IP in the command reference)
Position tracking error the difference between the
main Position Reference and the main Position
Feedback in counts.
The Current reference to the current controller in
amperes.
Bus voltage in volts.
Position accumulation of the auxiliary feedback
sensor in counts
Speed of auxiliary feedback sensor in counts/sec
The active part of the vectored current reference in
amperes.
The reactive part of the vectored current reference
in amperes.
Analog input 1 after offset compensation of AS[1]
in volts.
Phase A current in amperes.
Phase B current in amperes.
Speed reference to the speed controller in
counts/sec.
95
Table 8-2: Default mapping of recorded signals
After power-on, the recorder can access the first 16 signals tabulated above. In order to
access other signals, the recorder must make them available in a process called "mapping".
In the mapping process, the ID's of the desired signals is mapped to the recorder "cells". On
power-on, the signals of Table
The table below lists some more signals available to the recorder. The full list of recorded
signals may differ for Harmonica grades and releases. It can be retrieved from the
personality partition of the serial flash memory.
Signal
Signal Name (Command) Length –
ID
17 Field angle Short Stator field angle, 1024 counts per electrical
18 Commutation sensor
2
The word "cell" is used for a logical ID that can be directly referred by the recorder.
8-2 are mapped to the recorder "cells"2.
Description
Type
revolution
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Integer revolution, with origin at the electrical angle of
zero.
21 Filtered torque command Short The command to the Q current controller, at the
output of the command filter.
45 Motor DC supply voltage Short Sample Motor DC supply voltage.
64 External position reference Long -
Integer
Table 8-3: Some additional recorded signals
The part of the position reference generated by
external inputs.
Before recording a signal from Table 8-3, this signal must be "mapped to the recorder". In
the mapping process, the signal is given a logical ID that can be referred directly by the
recorder.
Up to sixteen signals may be mapped to the recorder at any time. Up to 8 signals can be
recorded at the same time.
The command RV[N]=x maps a signal with the ID of x to the logical ID of N, N=1..16.
RC is a bit field parameter (bit 0 to 15) that signals the recorder the actual required signal. In
our case the bit N-1 of RC points to signal x.
For example, RV[2]=1 maps the signal with the ID of 1 (the main encoder speed) to the
logical ID of 2. It means that in order to record the main encoder speed bit 1 of RC should
be set (RC=2).
The default mapping, restored at boot, maps the signals of ID's 1 to 16 to the corresponding
logical ID's 1..16. Thus the signals with the ID's 1..16 can be recorded by using the logical
ID's 1..16 respectively, without further programming.
If the user desires to record only signals with ID's in the range 1..16, he need not be aware to
the difference between signal ID's and logical ID's, and he need not program any mapping.
96
8.3 Defining the set of recorded signals
The command RC defines which of the mapped signals to record.
The RC command is a 16bit bit field. Each bit of RC specifies a logical signal ID to record.
For example, consider RC=5. The value 5 has the 16bit binary value of 0000000000000101.
The first and the third bits in the binary value of 5 are on, and the rest of the bits are zero.
RC=5 thus specifies that the signals with the logical ID's one and three shall be recorded,
and all the other signals will not.
Example:
The commands
RV[1]=5;RV[2]=1;RC=3;
defines that when the recorder will be launched, it will record the main speed and the
position error.
RC may define 8-recorded signals at most. In another words, the binary representation of
RC may not include more than eight one's.
8.4 Programming the length and the resolution
The length and the resolution of the recorded signals is programmed by the RP[0],RL, and
RG command.
RP[0] defines what is the basic time quantum of the recorder.
RP[0]=0 Synchronize the recorder to the speed or position control cycles. The time
quantum of the recorder will be
RP[0]=1 Synchronize the recorder to the torque cycles. The time quantum of the
recorder will be TS.
RP[0] is set automatically by the UM (Unit mode) command.
The torque mode UM=1 sets RP[0] to 0.
All the other unit modes set RP[0] to 1.
RG defines the sampling rate of the recorder, in terms of the time quantum.
TS4
⋅
Elmo HARmonica Software Manual
2 3 4 5 6 7 -1
0
1
occur here if set
for negative slope
occur here if set
for positive slope
occur here if set
for window
HARSFEN0602
P R E L I M I N A R Y D R A F T
RG=1 means that a new sample shall be taken once per time quantum. If TS=60, and
RP[0]=0, the recorder will sample once per 240usec.
RG=2 means that a new sample shall be taken once per two time quanta. If TS=60, and
RP[0]=1, the recorder will sample once per 120usec.
Similarly, RG=N means that a new sample shall be taken once per N time quanta.
Note that RG specifies only the recorder sampling-rate, not the trigger sampling-rate. A
trigger event will cause the recorder to start within one time quantum.
RL defines the number of maximal data items to collect.
For example, if RL=11, TS=60,RG=1, RP[0]=0, then the 11 samples at the rate of 240usec
shall be taken, lasting
secu240)111( ×− = 2400usec.
The recorder has a limited memory – total of 8kb. When more signals are recorded, less
memory is available for each recorded signal.
If
)signalsofnumber/()memoryrecorder(RL > , the recorder will fail to record the
specified RL samples – instead it will record to fill its data volume.
The actual amount of recorded data can be polled using WI[21].
8.5 Trigger events and timing
The recorder is started by a trigger event.
The trigger event may be one of the following:
•
Immediate: The recorder starts immediately after the recording request has been
issued.
•
Motion begin: The recorder is triggered by the execution of a software BG
command, or by timed BG command, or by a hardware commanded hardware
begin.
•
Triggered by an analog signal: The recorder starts upon the following event:
o Positive slope – The signal crosses a prescribed level with positive
slope
o Negative slope – The signal crosses a prescribed level with negative
slope
o Window – The signals exits a window of two prescribed signal
levels.
The picture below depicts the positive slope, negative slope, and window trigger types.
97
0.8
0.6
0.4
0.2
-0.2
-0.4
-0.6
-0.8
The trigger
1
Trigger signal (not necessarily
Level 1
The trigger
The trigger
Level 2
Elmo HARmonica Software Manual
HARSFEN0602
P R E L I M I N A R Y D R A F T
Figure 1 - Slope and window tr igger types
- Triggered by a digital signal: The Harmonica will support this only in the future, TBD.
Trigger delay
The trigger defines when the recorder is to start. The recorder can be told to start before the
trigger event, so that the trigger event can be caught in “the middle of the picture”. This is
possible since the recorder starts to record at the instance it is launched by the RR
command,
so that when the trigger event occurs, the pre-trigger information is already recorded.
The following picture examples this. The recorded signal is the speed. The trigger is set on
BG. After launching the recorder with RR=3, the command sequence JV=5000;BG is
entered. The results are shown in the picture below.
Note that in the above example, the recorder works for 10sec. Therefore, a pre-trigger delay of
20% requires 2 seconds to acquire the pre-trigger data. A BG command that is set less than 2
seconds after the RR=3 will be missed.
98
Loading...