classic-ladder.txt
1 [[cha:classicladder]] 2 3 = Classicladder Programming 4 5 == Ladder Concepts 6 7 Classic Ladder is a type of programming language originally 8 implemented on industrial PLCs (it's called Ladder Programming). It is 9 based on the concept of relay contacts and coils, and can be used to 10 construct logic checks and functions in a manner that is familiar to 11 many systems integrators. Ladder consists of rungs that may have 12 branches and resembles an electrical circuit. It is important to know 13 how ladder programs are evaluated when running. 14 15 It seems natural that each line would be evaluated left to right, then 16 the next line down, etc., but it doesn't work this way in ladder logic. 17 Ladder logic 'scans' the ladder rungs 3 times to change the state of the 18 outputs. 19 20 * the inputs are read and updated 21 * the logic is figured out 22 * the outputs are set 23 24 This can be confusing at first if the output of one line is read by the 25 input of a another rung. There will be one scan before the second input 26 becomes true after the output is set. 27 28 Another gotcha with ladder programming 29 is the "Last One Wins" rule. If you have the same output in different 30 locations of your ladder the state of the last one will be what the 31 output is set to. 32 33 == Languages 34 35 The most common language used when working with Classic Ladder is 36 'ladder'. Classic Ladder also supports Sequential Function Chart 37 (Grafcet). 38 39 == Components 40 41 There are 2 components to Classic Ladder. 42 43 * The real time module classicladder_rt 44 * The user space module (including a GUI) classicladder 45 46 === Files 47 48 Typically classic ladder components are placed in the custom.hal file 49 if your working from a Stepconf generated configuration. These must not 50 be placed in the custom_postgui.hal file or the Ladder Editor menu will 51 be grayed out. 52 53 NOTE: Ladder files (.clp) must not contain any blank spaces in the name. 54 55 === Realtime Module 56 57 Loading the Classic Ladder real time module (classicladder_rt) is 58 possible from a HAL file, or directly using a halcmd instruction. The 59 first line loads real time the Classic Ladder module. The second line 60 adds the function classicladder.0.refresh to the servo thread. This 61 line makes Classic Ladder update at the servo thread rate. 62 63 ---- 64 loadrt classicladder_rt 65 addf classicladder.0.refresh servo-thread 66 ---- 67 68 The speed of the thread that Classic Ladder is running in directly 69 affects the responsiveness to inputs and outputs. If you can turn a 70 switch on and off faster than Classic Ladder can notice it then you may 71 need to speed up the thread. The fastest that Classic Ladder can update 72 the rungs is one millisecond. You can put it in a faster thread but it 73 will not update any faster. If you put it in a slower than one 74 millisecond thread then Classic Ladder will update the rungs slower. 75 The current scan time will be displayed on the section display, it is 76 rounded to microseconds. If the scan time is longer than one 77 millisecond you may want to shorten the ladder or put it in a slower 78 thread. 79 80 === Variables 81 82 It is possible to configure the number of each type of ladder object 83 while loading the Classic Ladder real time module. If you do not 84 configure the number of ladder objects Classic Ladder will use the 85 default values. 86 87 .Default Variable Count 88 89 [width="90%", options="header", cols="<8,<4,<2"] 90 |======================================== 91 |Object Name | Variable Name | Default Value 92 |Number of rungs | (numRungs) | 100 93 |Number of bits | (numBits) | 20 94 |Number of word variables | (numWords) | 20 95 |Number of timers | (numTimers) | 10 96 |Number of timers IEC | (numTimersIec) | 10 97 |Number of monostables | (numMonostables) | 10 98 |Number of counters | (numCounters) | 10 99 |Number of HAL inputs bit pins | (numPhysInputs) | 15 100 |Number of HAL output bit pins | (numPhysOutputs) | 15 101 |Number of arithmetic expressions | (numArithmExpr) | 50 102 |Number of Sections | (numSections) | 10 103 |Number of Symbols | (numSymbols) | Auto 104 |Number of S32 inputs | (numS32in) | 10 105 |Number of S32 outputs | (numS32out) | 10 106 |Number of Float inputs | (numFloatIn) | 10 107 |Number of Float outputs | (numFloatOut) | 10 108 |======================================== 109 110 Objects of most interest are numPhysInputs, numPhysOutputs, numS32in, 111 and numS32out. 112 113 Changing these numbers will change the number of HAL bit pins 114 available. numPhysInputs and numPhysOutputs control how many HAL bit 115 (on/off) pins are available. numS32in and numS32out control how many 116 HAL signed integers (+- integer range) pins are available. 117 118 For example (you don't need all of these to change just a few): 119 120 ---- 121 loadrt classicladder_rt numRungs=12 numBits=100 numWords=10 122 numTimers=10 numMonostables=10 numCounters=10 numPhysInputs=10 123 numPhysOutputs=10 numArithmExpr=100 numSections=4 numSymbols=200 124 numS32in=5 numS32out=5 125 ---- 126 127 To load the default number of objects: 128 129 ---- 130 loadrt classicladder_rt 131 ---- 132 133 == Loading the Classic Ladder user module 134 135 Classic Ladder HAL commands must executed before the GUI loads or the 136 menu item Ladder Editor will not function. If you used the Stepper 137 Config Wizard place any Classic Ladder HAL commands in the custom.hal 138 file. 139 140 To load the user module: 141 142 ---- 143 loadusr classicladder 144 ---- 145 146 NOTE: Only one .clp file can be loaded. If you need to divide your ladder 147 use Sections. 148 149 To load a ladder file: 150 151 ---- 152 loadusr classicladder myladder.clp 153 ---- 154 155 Classic Ladder Loading Options 156 157 * '--nogui' - (loads without the ladder editor) normally used after 158 debugging is finished. 159 * '--modbus_port=port' - (loads the modbus port number) 160 * '--modmaster' - (initializes MODBUS master) should load the ladder 161 program at the same time or the TCP is default port. 162 * '--modslave' - (initializes MODBUS slave) only TCP 163 164 To use Classic Ladder with HAL without EMC: 165 166 ---- 167 loadusr -w classicladder 168 ---- 169 170 The -w tells HAL not to close down the HAL environment 171 until Classic Ladder is finished. 172 173 If you first load ladder program with the '--nogui' option then load 174 Classic Ladder again with no options the GUI 175 will display the last loaded ladder program. 176 177 In AXIS you can load the GUI from File/Ladder Editor... 178 179 == Classic Ladder GUI 180 181 If you load Classic Ladder with the GUI it will display two windows: 182 section display, and section manager. 183 184 === Sections Manager 185 186 When you first start up Classic Ladder you get an empty Sections 187 Manager window. 188 189 .Sections Manager Default Window 190 191 image::images/Default_Sections_Manager.png[align="center", alt="Sections Manager Default Window"] 192 193 This window allows you to name, create or delete sections and choose 194 what language that section uses. This is also how you name a subroutine 195 for call coils. 196 197 === Section Display 198 199 When you first start up Classic Ladder you get an empty Section 200 Display window. Displayed is one empty rung. 201 202 .Section Display Default Window 203 204 image::images/Default_Section_Display.png[align="center", alt="Section Display Default Window"] 205 206 Most of the buttons are self explanatory: 207 208 The Vars button is for looking at variables, toggle it to display one, 209 the other, both, then none of the windows. 210 211 The Config button is used for modbus and shows the max number of 212 ladder elements that was loaded with the real time module. 213 214 The Symbols button will display an editable list of symbols for the 215 variables (hint you can name the inputs, outputs, coils etc). 216 217 The Quit button will shut down the user program meaning Modbus and the 218 display. The real time ladder program will still run in the background. 219 220 The check box at the top right allows you to select whether variable 221 names or symbol names are displayed 222 223 You might notice that there is a line under the ladder program display 224 that reads "Project failed to load..." That is the status bar that 225 gives you info about elements of the ladder program that you click on 226 in the display window. This status line will now display HAL signal 227 names for variables %I, %Q and the first %W (in an equation) You might 228 see some funny labels, such as (103) in the rungs. This is displayed 229 (on purpose) because of an old bug- when erasing elements older 230 versions sometimes didn't erase the object with the right code. You 231 might have noticed that the long horizontal connection button sometimes 232 didn't work in the older versions. This was because it looked for the 233 'free' code but found something else. The number in the brackets is the 234 unrecognized code. The ladder program will still work properly, to fix 235 it erase the codes with the editor and save the program. 236 237 === The Variable Windows 238 239 This are two variable windows: the Bit Status Window (boolean) and 240 the Watch Window (signed integer). The Vars 241 button is in the Section Display Window, toggle the Vars button to 242 display one, the other, both, then none of the variable windows. 243 244 .Bit Status Window 245 246 image::images/Bit_Status.png[align="center",alt="Bit Status Window"] 247 248 The Bit Status Window displays some of the boolean (on/off) variable data. 249 Notice all variables start with the % sign. The %I variables represent 250 HAL input bit pins. The %Q represents the relay coil and HAL output bit 251 pins. The %B represents an internal relay coil or internal contact. The 252 three edit areas at the top allow you to select what 15 variables will 253 be displayed in each column. For instance, if the %B Variable column 254 were 15 entries high, 255 and you entered 5 at the top of the column, variables %B5 to %B19 would 256 be displayed. The check boxes allow you to set and unset %B variables 257 manually as long as the ladder program isn't setting them as outputs. 258 Any Bits that are set as outputs by the program when Classic Ladder is 259 running can not be changed and will be displayed as checked if on and 260 unchecked if off. 261 262 .Watch Window 263 264 image::images/watch_window.png[align="center", alt="Watch Window"] 265 266 The Watch Window displays variable status. The edit box beside it is 267 the number stored in the variable and the drop-down box beside that 268 allow you to choose whether the number to be displayed in hex, decimal 269 or binary. If there are symbol names defined in the symbols window for 270 the word variables showing and the 'display symbols' checkbox is 271 checked in the section display window, symbol names will be displayed. 272 To change the variable displayed, type the variable number, e.g. %W2 (if 273 the display symbols check box is not checked) or type the symbol name 274 (if the display symbols checkbox is checked) over an existing variable 275 number/name and press the Enter Key. 276 277 === Symbol Window 278 279 .Symbol Names window 280 281 image::images/Default_Symbols_names.png[align="center", alt="Symbol Names window"] 282 283 This is a list of 'symbol' names to use instead of variable names to 284 be displayed in the section window when the 'display symbols' check box 285 is checked. You add the variable name (remember the '%' symbol and 286 capital letters), symbol name . If the variable can have a HAL signal 287 connected to it (%I, %Q, and %W-if you have loaded s32 pin with the 288 real time module) then the comment section will show the current HAL 289 signal name or lack thereof. Symbol names should be kept short to 290 display better. Keep in mind that you can display the longer HAL signal 291 names of %I, %Q and %W variable by clicking on them in the section 292 window. Between the two, one should be able to keep track of what the 293 ladder program is connected to! 294 295 === The Editor window 296 297 .Editor Window 298 299 image::images/Editor.png[align="center", alt="Editor Window"] 300 301 * 'Add' - adds a rung after the selected rung 302 * 'Insert' - inserts a rung before the selected rung 303 * 'Delete' - deletes the selected rung 304 * 'Modify' - opens the selected rung for editing 305 306 Starting from the top left image: 307 308 * Object Selector, Eraser 309 * N.O. Input, N.C. Input, Rising Edge Input , Falling Edge Input 310 * Horizontal Connection, Vertical Connection , Long Horizontal Connection 311 * Timer IEC Block, Counter Block, Compare Variable 312 * Old Timer Block, Old Monostable Block (These have been replaced by the 313 IEC Timer) 314 * COILS - N.O. Output, N.C. Output, Set Output, Reset Output 315 * Jump Coil, Call Coil, Variable Assignment 316 317 A short description of each of the buttons: 318 319 * 'Selector' - allows you to select existing objects and 320 modify the information. 321 * 'Eraser' - erases an object. 322 * 'N.O. Contact' - creates a normally open contact. It can be an external 323 HAL-pin (%I) input contact, an internal-bit coil (%B) contact or a 324 external coil (%Q) contact. The HAL-pin input contact is closed when 325 the HAL-pin is true. The coil contacts are closed when the 326 corresponding coil is active (%Q2 contact closes when %Q2 coil is 327 active). 328 * 'N.C. Contact' - creates a normally closed contact. It is the same as the 329 N.O. contact except that the contact is open when the HAL-pin is true 330 or the coil is active. 331 * 'Rising Edge Contact - creates a contact that is closed when the HAL-pin 332 goes from False to true, or the coil from not-active to active. 333 * 'Falling Edge Contact' - creates a contact that is closed when the HAL-pin 334 goes from true to false or the coil from active to not. 335 * 'Horizontal Connection' - creates a horizontal connection to objects. 336 * 'Vertical Connection' - creates a vertical connection to horizontal lines. 337 * 'Horizontal Running Connection' - creates a horizontal connection between 338 two objects and is a quick way to connect objects that are more than one 339 block apart. 340 * 'IEC Timer' - creates a timer and replaces the 'Timer'. 341 * 'Timer' - creates a Timer Module (depreciated use IEC Timer instead). 342 * 'Monostable' - creates a one-shot monostable module 343 * 'Counter' - creates a counter module. 344 * 'Compare' - creates a compare block to compare variable to values or other 345 variables. (eg %W1<=5 or %W1=%W2) Compare cannot be placed in the right 346 most side of the section display. 347 * 'Variable Assignment' - creates an assignment block so you to assign values to 348 variables. (eg %W2=7 or %W1=%W2) ASSIGNMENT functions can only be 349 placed at the right most side of the section display. 350 351 === Config Window 352 353 The config window shows the current project status and has the Modbus 354 setup tabs. 355 356 .Config Window 357 358 image::images/Config.png[align="center", alt="Config Window"] 359 360 == Ladder objects 361 362 === CONTACTS 363 364 Represent switches or relay contacts. They are controlled by the 365 variable letter and number assigned to them. 366 367 The variable letter can be B, I, or Q and the number can be up to a 368 three digit number eg. %I2, %Q3, or %B123. Variable I is controlled by 369 a HAL input pin with a corresponding number. Variable B is for 370 internal contacts, controlled by a B coil with a corresponding number. 371 Variable Q is controlled by a Q coil with a corresponding number. (like 372 a relay with multiple contacts). E.g. if HAL pin classicladder.0.in-00 373 is true then %I0 N.O. contact would be on (closed, true, whatever you 374 like to call it). If %B7 coil is 'energized' (on, true, etc) then %B7 375 N.O. contact would be on. If %Q1 coil is 'energized' then %Q1 N.O. 376 contact would be on (and HAL pin classicladder.0.out-01 would be true.) 377 378 * 'N.O. Contact' - image:images/ladder_action_load.png[alt="Normally Open Contact"] (Normally Open) 379 When the variable is false the switch is off. 380 * 'N.C. Contact' - image:images/ladder_action_loadbar.png[alt="Normally Closed Contact"] (Normally 381 Closed) When the variable is false the switch is on. 382 * 'Rising Edge Contact' - When the variable changes from false to true, 383 the switch is PULSED on. 384 * 'Falling Edge Contact' - When the variable changes from true to false, 385 the switch is PULSED on. 386 387 === IEC TIMERS 388 389 Represent new count down timers. IEC Timers replace Timers and 390 Monostables. 391 392 IEC Timers have 2 contacts. 393 394 * 'I' - input contact 395 * 'Q' - output contact 396 397 There are three modes - TON, TOF, TP. 398 399 * 'TON' - When timer input is true countdown begins and continues as long 400 as input remains true. After countdown is done and as long as timer 401 input is still true the output will be true. 402 * 'TOF' - When timer input is true, sets output true. When the input is 403 false the timer counts down then sets output false. 404 * 'TP' - When timer input is pulsed true or held true timer sets output 405 true till timer counts down. (one-shot) 406 407 The time intervals can be set in multiples of 100ms, seconds, or 408 minutes. 409 410 There are also Variables for IEC timers that can be read and/or 411 written to in compare or operate blocks. 412 413 * '%TMxxx.Q' - timer done (Boolean, read write) 414 * '%TMxxx.P' - timer preset (read write) 415 * '%TMxxx.V' - timer value (read write) 416 417 === TIMERS 418 419 Represent count down timers. This is deprecated and replaced by IEC 420 Timers. 421 422 Timers have 4 contacts. 423 424 * 'E' - enable (input) starts timer when true, resets when goes false 425 * 'C' - control (input) must be on for the timer to run (usually connect to E) 426 * 'D' - done (output) true when timer times out and as long as E remains true 427 * 'R' - running (output) true when timer is running 428 429 The timer base can be multiples of milliseconds, seconds, or minutes. 430 431 There are also Variables for timers that can be read and/or written to 432 in compare or operate blocks. 433 434 * '%Txx.R' - Timer xx running (Boolean, read only) 435 * '%Txx.D' - Timer xx done (Boolean, read only) 436 * '%Txx.V' - Timer xx current value (integer, read only) 437 * '%Txx.P' - Timer xx preset (integer, read or write) 438 439 === MONOSTABLES 440 441 Represent the original one-shot timers. This is now 442 deprecated and replaced by IEC Timers. 443 444 Monostables have 2 contacts, I and R. 445 446 * 'I' - input (input) will start the mono timer running. 447 * 'R' - running (output) will be true while timer is running. 448 449 The I contact is rising edge sensitive meaning it starts the timer 450 only when changing from false to true (or off to on). While the timer 451 is running the I contact can change with no effect to the running 452 timer. R will be true and stay true till the timer finishes counting to 453 zero. The timer base can be multiples of milliseconds, seconds, or 454 minutes. 455 456 There are also Variables for monostables that can be read and/or 457 written to in compare or operate blocks. 458 459 * '%Mxx.R' - Monostable xx running (Boolean, read only) 460 * '%Mxx.V' - Monostable xx current value (integer, read only) 461 * '%Mxx.P' - Monostable xx preset (integer, read or write) 462 463 === COUNTERS 464 465 Represent up/down counters. 466 467 There are 7 contacts: 468 469 * 'R' - reset (input) will reset the count to 0. 470 * 'P' - preset (input) will set the count to the preset number assigned 471 from the edit menu. 472 * 'U' - up count (input) will add one to the count. 473 * 'D' - down count (input) will subtract one from the count. 474 * 'E' - under flow (output) will be true when the count rolls over from 0 475 to 9999. 476 * 'D' - done (output) will be true when the count equals the preset. 477 * 'F' - overflow (output) will be true when the count rolls over from 9999 478 to 0. 479 480 The up and down count contacts are edge sensitive meaning they only 481 count when the contact changes from false to true (or off to on if you 482 prefer). 483 484 The range is 0 to 9999. 485 486 There are also Variables for counters that can be read and/or written 487 to in compare or operate blocks. 488 489 * '%Cxx.D' - Counter xx done (Boolean, read only) 490 * '%Cxx.E' - Counter xx empty overflow (Boolean, read only) 491 * '%Cxx.F' - Counter xx full overflow (Boolean, read only) 492 * '%Cxx.V' - Counter xx current value (integer, read or write) 493 * '%Cxx.P' - Counter xx preset (integer, read or write) 494 495 === COMPARE 496 497 For arithmetic comparison. Is variable %XXX = to this number (or 498 evaluated number) 499 500 The compare block will be true when comparison is true. you can use 501 most math symbols: 502 503 * +, - ,* , /, = (standard math symbols) 504 * < (less than), > (greater than), <= (less or equal), >= (greater or 505 equal), <> (not equal) 506 * (, ) separate into groups example %IF1=2,&%IF2<5 in pseudo code translates to 507 if %IF1 is equal to 2 and %IF2 is less than 5 then the comparison is true. 508 Note the comma seperating the two groups of comparisions. 509 * ^ (exponent),% (modulus),& (and),| (or),. - 510 * ABS (absolute), MOY (French for average) ,AVG (average) 511 512 For example ABS(%W2)=1, MOY(%W1,%W2)<3. 513 514 No spaces are allowed in the comparison equation. For example 515 %C0.V>%C0.P is a valid comparison expression while %C0.V > %CO.P is not 516 a valid expression. 517 518 There is a list of Variables down the page that can be used for 519 reading from and writing to ladder objects. When a new compare block is opened 520 be sure and delete the # symbol when you enter a compare. 521 522 To find out if word variable #1 is less than 2 times the current value 523 of counter #0 the syntax would be: 524 525 ---- 526 %W1<2*%C0.V 527 ---- 528 529 To find out if S32in bit 2 is equal to 10 the syntax would be: 530 531 ---- 532 %IW2=10 533 ---- 534 535 Note: Compare uses the arithmetic equals not the double equals that 536 programmers are used to. 537 538 === VARIABLE ASSIGNMENT 539 540 For variable assignment, e.g. assign this number (or evaluated number) 541 to this variable %xxx, there are two math functions MINI and MAXI that 542 check a variable for maximum (0x80000000) and minimum values 543 (0x07FFFFFFF) (think signed values) and keeps them from going beyond. 544 545 When a new variable assignment block is opened be sure to delete the 546 # symbol when you enter an assignment. 547 548 To assign a value of 10 to the timer preset of IEC Timer 0 the syntax 549 would be: 550 551 ---- 552 %TM0.P=10 553 ---- 554 555 To assign the value of 12 to s32out bit 3 the syntax would be: 556 557 ---- 558 %QW3=12 559 ---- 560 561 [NOTE] 562 When you assign a value to a variable with the variable assignment block 563 the value is retained until you assign a new value using the variable 564 assignment block. The last value assigned will be restored when LinuxCNC 565 is started. 566 567 The following figure shows an Assignment and a Comparison Example. 568 %QW0 is a S32out bit and %IW0 is a S32in bit. In this case the HAL pin 569 classicladder.0.s32out-00 will be set to a value of 5 and when the HAL 570 pin classicladder.0.s32in-00 is 0 the HAL pin classicladder.0.out-00 571 will be set to True. 572 573 .Assign/Compare Example 574 575 image::images/AssignCompare-Ladder.png[align="center", alt="Assign/Compare Example"] 576 577 image::images/Assignment_Expression.png[align="center"] 578 579 image::images/Comparison_Expression.png[align="center"] 580 581 === COILS 582 583 Coils represent relay coils. They are controlled by the variable 584 letter and number assigned to them. 585 586 The variable letter can be B or Q and the number can be up to a three 587 digit number eg. %Q3, or %B123. Q coils control HAL out pins, e.g. if 588 %Q15 is energized then HAL pin classicladder.0.out-15 will be true. B 589 coils are internal coils used to control program flow. 590 591 * 'N.O. COIL' - (a relay coil.) When coil is energized it's N.O. contact 592 will be closed (on, true, etc) 593 * 'N.C. COIL' - (a relay coil that inverses its contacts.) When coil is 594 energized it"s N.O. contact will be open (off, false, etc) 595 * 'SET COIL' - (a relay coil with latching contacts) When coil is energized 596 it's N.O. contact will be latched closed. 597 * 'RESET COIL' - (a relay coil with latching contacts) When coil is 598 energized It's N.0. contact will be latched open. 599 * 'JUMP COIL' - (a 'goto' coil) when coil is energized ladder program jumps 600 to a rung (in the CURRENT section) -jump points are designated by a 601 rung label. (Add rung labels in the section display, top left label 602 box) 603 * 'CALL COIL' - (a 'gosub' coil) when coil is energized program jumps to a 604 subroutine section designated by a subroutine number -subroutines are 605 designated SR0 to SR9 (designate them in the section manager) 606 607 [WARNING] 608 If you use a N.C. contact with a N.C. coil the logic 609 will work (when the coil is energized the contact will be closed) but 610 that is really hard to follow! 611 612 .JUMP COIL 613 614 A JUMP COIL is used to 'JUMP' to another section, like a goto in BASIC 615 programming language. 616 617 If you look at the top left of the sections display window you will 618 see a small label box and a longer comment box beside it. Now go to 619 Editor→Modify then go back to the little box, type in a name. 620 621 Go ahead and add a comment in the comment section. This label name is 622 the name of this rung only and is used by the JUMP COIL to identify 623 where to go. 624 625 When placing a JUMP COIL, add it in the rightmost position and change 626 the label to the rung you want to JUMP to. 627 628 .CALL COIL 629 630 A CALL COIL is used to go to a subroutine section then return, like a 631 gosub in BASIC programming language. 632 633 If you go to the sections manager window hit the add section button. 634 You can name this section, select what language it will use (ladder or 635 sequential), and select what type (main or subroutine). 636 637 Select a subroutine number (SR0 for example). An empty section will be 638 displayed and you can build your subroutine. 639 640 When you've done that, go back to the section manager and click on the 641 your main section (default name prog1). 642 643 Now you can add a CALL COIL to your program. CALL COILs are to be 644 placed at the rightmost position in the rung. 645 646 Remember to change the label to the subroutine number you chose before. 647 648 == Classic Ladder Variables 649 650 These Variables are used in COMPARE or OPERATE to get information 651 about, or change specs of, ladder objects such as changing a counter 652 preset, or seeing if a timer is done running. 653 654 List of variables : 655 656 * '%Bxxx' - Bit memory xxx (Boolean) 657 * '%Wxxx' - Word memory xxx (32 bits signed integer) 658 * '%IWxxx' - Word memory xxx (S32 in pin) 659 * '%QWxxx' - Word memory xxx (S32 out pin) 660 * '%IFxx' - Word memory xx (Float in pin) (*converted to S32 in Classic 661 Ladder*) 662 * '%QFxx' - Word memory xx (Float out pin) (*converted to S32 in Classic 663 Ladder*) 664 * '%Txx.R' - Timer xx running (Boolean, user read only) 665 * '%Txx.D' - Timer xx done (Boolean, user read only) 666 * '%Txx.V' - Timer xx current value (integer, user read only) 667 * '%Txx.P' - Timer xx preset (integer) 668 * '%TMxxx.Q' - Timer xxx done (Boolean, read write) 669 * '%TMxxx.P' - Timer xxx preset (integer, read write) 670 * '%TMxxx.V' - Timer xxx value (integer, read write) 671 * '%Mxx.R' - Monostable xx running (Boolean) 672 * '%Mxx.V' - Monostable xx current value (integer, user read only) 673 * '%Mxx.P' - Monostable xx preset (integer) 674 * '%Cxx.D' - Counter xx done (Boolean, user read only) 675 * '%Cxx.E' - Counter xx empty overflow (Boolean, user read only) 676 * '%Cxx.F' - Counter xx full overflow (Boolean, user read only) 677 * '%Cxx.V' - Counter xx current value (integer) 678 * '%Cxx.P' - Counter xx preset (integer) 679 * '%Ixxx' - Physical input xxx (Boolean) (HAL input bit) 680 * '%Qxxx' - Physical output xxx (Boolean) (HAL output bit) 681 * '%Xxxx' - Activity of step xxx (sequential language) 682 * '%Xxxx.V' - Time of activity in seconds of step xxx (sequential language) 683 * '%Exx' - Errors (Boolean, read write(will be overwritten)) 684 * 'Indexed or vectored variables' - These are variables indexed by another 685 variable. Some might call this vectored variables. Example: %W0[%W4] => 686 if %W4 equals 23 it corresponds to %W23 687 688 == GRAFCET (State Machine) Programming 689 690 [WARNING] 691 This is probably the least used and most poorly understood 692 feature of Classic Ladder. 693 Sequential programming is used to make sure a series of 694 ladder events always happen in a prescribed order. Sequential programs 695 do not work alone. There is always a ladder program as well that 696 controls the variables. Here are the basic rules governing sequential 697 programs: 698 699 * Rule 1 : Initial situation - The initial situation is characterized by 700 the initial steps which are by definition in the active state at the 701 beginning of the operation.There shall be at least one initial step. 702 * Rule 2 : R2, Clearing of a transition - A transition is either enabled 703 or disabled. It is said to be enabled when all immediately preceding 704 steps linked to its corresponding transition symbol are active, 705 otherwise it is disabled. A transition cannot be cleared unless it is 706 enabled, and its associated transition condition is true. 707 * Rule 3 : R3, Evolution of active steps - The clearing of a transition 708 simultaneously leads to the active state of the immediately following 709 step(s) and to the inactive state of the immediately preceding step(s). 710 * Rule 4 : R4, Simultaneous clearing of transitions - All simultaneous 711 cleared transitions are simultaneously cleared. 712 * Rule 5 : R5, Simultaneous activation and deactivation of a step - If 713 during operation, a step is simultaneously activated and deactivated, 714 priority is given to the activation. 715 716 This is the SEQUENTIAL editor window Starting from the top left image: 717 Selector arrow , Eraser Ordinary step , Initial (Starting) step 718 Transition , Step and Transition Transition Link-Downside , Transition 719 Link-Upside Pass-through Link-Downside , Pass-through Link-Upside Jump 720 Link Comment Box [show sequential program] 721 722 * 'ORDINARY STEP' - has a unique number for each one 723 * 'STARTING STEP' - a sequential program must have one. This is where the 724 program will start. 725 * 'TRANSITION' - This shows the variable that must be true for control to 726 pass through to the next step. 727 * 'STEP AND TRANSITION' - Combined for convenience 728 * 'TRANSITION LINK-DOWNSIDE' - splits the logic flow to one of two possible 729 lines based on which of the next steps is true first (Think OR logic) 730 * 'TRANSITION LINK=UPSIDE' - combines two (OR) logic lines back in to one 731 * 'PASS-THROUGH LINK-DOWNSIDE' - splits the logic flow to two lines that 732 BOTH must be true to continue (Think AND logic) 733 * 'PASS-THROUGH LINK-UPSIDE' - combines two concurrent (AND logic) logic 734 lines back together 735 * 'JUMP LINK' - connects steps that are not underneath each other such as 736 connecting the last step to the first 737 * 'COMMENT BOX' - used to add comments 738 739 To use links, you must have steps already placed. Select the type of 740 link, then select the two steps or transactions one at a time. It 741 takes practice! 742 743 With sequential programming: The variable %Xxxx (eg. %X5) is used to 744 see if a step is active. The variable %Xxxx.V (eg. %X5.V) is used to 745 see how long the step has been active. The %X and %X.v variables are 746 use in LADDER logic. The variables assigned to the transitions (eg. %B) 747 control whether the logic will pass to the next step. After a step has 748 become active the transition variable that caused it to become active 749 has no control of it anymore. The last step has to JUMP LINK back only 750 to the beginning step. 751 752 == Modbus 753 754 Things to consider: 755 756 * Modbus is a userspace program so it might have latency issues on a 757 heavily laden computer. 758 * Modbus is not really suited to Hard real time events such as position 759 control of motors or to control E-stop. 760 * The Classic Ladder GUI must be running for Modbus to be running. 761 * Modbus is not fully finished so it does not do all modbus functions. 762 763 To get MODBUS to initialize you must specify that when loading the 764 Classic Ladder userspace program. 765 766 .Loading Modbus 767 ---- 768 loadusr -w classicladder --modmaster myprogram.clp 769 ---- 770 771 The -w makes HAL wait until you close Classic Ladder before closing realtime 772 session. Classic Ladder also loads a TCP modbus slave if you add '--modserver' 773 on command line. 774 775 .Modbus Functions 776 * '1' - read coils 777 * '2' - read inputs 778 * '3' - read holding registers 779 * '4' - read input registers 780 * '5' - write single coils 781 * '6' - write single register 782 * '8' - echo test 783 * '15' - write multiple coils 784 * '16' - write multiple registers 785 786 If you do not specify a '-- modmaster' when loading the Classic Ladder user 787 program this page will not be displayed. 788 789 .Config I/O 790 791 image::images/Config-io.png[align="center", alt="Config I/O"] 792 793 .Config Coms 794 795 image::images/Config-com.png[align="center", alt="Config Coms"] 796 797 * 'SERIAL PORT' - For IP blank. For serial the location/name of serial driver eg. 798 /dev/ttyS0 ( or /dev/ttyUSB0 for a USB-to-serial converter). 799 800 * 'SERIAL SPEED' - Should be set to speed the slave is set for - 300, 600, 1200, 2400, 801 4800, 9600, 19200, 38400, 57600, 115200 are supported. 802 803 * 'PAUSE AFTER TRANSMIT' - Pause (milliseconds) after transmit and before receiving answer, 804 some devices need more time (e.g., USB-to-serial converters). 805 806 * 'PAUSE INTER-FRAME' - Pause (milliseconds) after receiving answer from slave. This sets 807 the duty cycle of requests (it's a pause for EACH request). 808 809 * 'REQUEST TIMEOUT LENGTH' - Length (milliseconds) of time before we decide that the slave didn't 810 answer. 811 812 * 'MODBUS ELEMENT OFFSET' - used to offset the element numbers by 1 (for manufacturers numbering 813 differences). 814 815 * 'DEBUG LEVEL' - Set this to 0-3 (0 to stop printing debug info besides no-response 816 errors). 817 818 * 'READ COILS/INPUTS MAP TO' - Select what variables that read coils/inputs will update. (B or Q). 819 820 * 'WRITE COILS MAP TO' - Select what variables that write coils will updated.from (B,Q,or I). 821 822 * 'READ REGISTERS/HOLDING' - Select what variables that read registers will update. (W or QW). 823 824 * 'WRITE REGISTERS MAP TO' - Select what variables that read registers will updated from. (W, QW, 825 or IW). 826 827 * 'SLAVE ADDRESS' - For serial the slaves ID number usually settable on the slave device 828 (usually 1-256) For IP the slave IP address plus optionally the port 829 number. 830 831 * 'TYPE ACCESS' - This selects the MODBUS function code to send to the slave (eg what 832 type of request). 833 834 * 'COILS / INPUTS' - Inputs and Coils (bits) are read from/written to I, B, or Q variables (user selects). 835 836 * 'REGISTERS (WORDS)' - Registers (Words/Numbers) map to IW, W, or QW variables (user selects). 837 838 * '1st MODBUS ELEMENT' - The address (or register number) of the first element in a group. 839 (remember to set MODBUS ELEMENT OFFSET properly). 840 841 * 'NUMBER OF ELEMENTS' - The number of elements in this group. 842 843 * 'LOGIC' - You can invert the logic here. 844 845 * '1st%I%Q IQ WQ MAPPED' - This is the starting number of %B, %I, %Q, %W, %IW, or %QW variables 846 that are mapped onto/from the modbus element group (starting at the 847 first modbus element number). 848 849 In the example above: Port number - for my computer /dev/ttyS0 was my 850 serial port. 851 852 The serial speed is set to 9600 baud. 853 854 Slave address is set to 12 (on my VFD I can set this from 1-31, 855 meaning I can talk to 31 VFDs maximum on one system). 856 857 The first line is set up for 8 input bits starting at the first 858 register number (register 1). So register numbers 1-8 are mapped onto 859 Classic Ladder's %B variables starting at %B1 and ending at %B8. 860 861 The second line is set for 2 output bits starting at the ninth 862 register number (register 9) so register numbers 9-10 are mapped onto 863 Classic Ladder's %Q variables starting at %Q9 ending at %Q10. 864 865 The third line is set to write 2 registers (16 bits each) starting at 866 the 0th register number (register 0) so register numbers 0-1 are 867 mapped onto Classic Ladder's %W variables starting at %W0 ending at %W1. 868 869 It's easy to make an off-by-one error as sometimes the modbus elements 870 are referenced starting at one rather then 0 (actually by the standard 871 that is the way it's supposed to be!) You can use the modbus element 872 offset radio button to help with this. 873 874 The documents for your modbus slave device will tell you how the 875 registers are set up- there is no standard way. 876 877 The SERIAL PORT, PORT SPEED, PAUSE, and DEBUG level are editable for 878 changes (when you close the config window values are applied, though 879 Radio buttons apply immediately). 880 881 To use the echo function select the echo function and add the slave 882 number you wish to test. You don't need to specify any variables. 883 884 The number 257 will be sent to the slave number you specified and the 885 slave should send it back. you will need to have Classic Ladder running 886 in a terminal to see the message. 887 888 === MODBUS Settings 889 890 Serial: 891 892 * Classic Ladder uses RTU protocol (not ASCII). 893 * 8 data bits, No parity is used, and 1 stop bit is also known as 8-N-1. 894 * Baud rate must be the same for slave and master. Classic Ladder can 895 only have one baud rate so all the slaves must be set to the same rate. 896 * Pause inter frame is the time to pause after receiving an answer. 897 * MODBUS_TIME_AFTER_TRANSMIT is the length of pause after sending a 898 request and before receiving an answer (this apparently helps with USB 899 converters which are slow). 900 901 === MODBUS Info 902 903 * Classic Ladder can use distributed inputs/outputs on modules using the 904 modbus protocol ("master": polling slaves). 905 * The slaves and theirs I/O can be configured in the config window. 906 * 2 exclusive modes are available : ethernet using Modbus/TCP and serial 907 using Modbus/RTU. 908 * No parity is used. 909 * If no port name for serial is set, TCP/IP mode will be used... 910 * The slave address is the slave address (Modbus/RTU) or the IP address. 911 * The IP address can be followed per the port number to use 912 (xx.xx.xx.xx:pppp) else the port 9502 will be used per default. 913 * 2 products have been used for tests: a Modbus/TCP one (Adam-6051, 914 http://www.advantech.com) and a serial Modbus/RTU one 915 (http://www.ipac.ws). 916 * See examples: adam-6051 and modbus_rtu_serial. 917 * Web links: http://www.modbus.org and this interesting one: 918 http://www.iatips.com/modbus.html 919 * MODBUS TCP SERVER INCLUDED 920 * Classic Ladder has a Modbus/TCP server integrated. Default port is 9502. 921 (the previous standard 502 requires that the application must be 922 launched with root privileges). 923 * List of Modbus functions code supported are: 1, 2, 3, 4, 5, 6, 15 and 16. 924 * Modbus bits and words correspondence table is actually not parametric 925 and correspond directly to the %B and %W variables. 926 927 More information on modbus protocol is available on the internet. 928 929 http://www.modbus.org/[http://www.modbus.org/] 930 931 === Communication Errors 932 933 If there is a communication error, a warning window will pop up (if 934 the GUI is running) and %E0 will be true. Modbus will continue to try 935 to communicate. The %E0 could be used to make a decision based on the 936 error. A timer could be used to stop the machine if timed out, etc. 937 938 === Debugging modbus problems 939 A good reference for the protocol: + 940 http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b.pdf + 941 If you run linuxcnc/classocladder from a terminal, it will print 942 the Modbus commands and slave responses. + 943 944 Here we set Classiclader to request slave 1, + 945 to read holding registers (function code 3) starting at address 8448 (0x2100) + 946 We ask for 1 (2 byte wide) data element to be returned + 947 We map it to a Classicladder variable starting at 2 + 948 949 image::images/modbus_register_setting.png[align="center", alt="Config I/O Register Setting"] 950 951 Note in this image we have set the debug level to 1 so modbus messages are printed to the terminal + 952 We have mapped our read and written holding registers to classicladder's %W variables + 953 so our returned data will be in %W2 as in the other image we mapped the data starting at the 2nd element + 954 955 image::images/modbus_com_setting.png[align="center", alt="Comunication Setting"] 956 957 ==== Request 958 Lets look at an example of reading one hold register at 8448 Decimal (0x2100 Hex) + 959 960 Looking in the Modbus protocol reference: + 961 962 .Read holding register request 963 964 [width="50%", options="header", cols="<6,<2,<6"] 965 |======================================== 966 |Name | number of bytes | Value (hex) 967 |Function code | (1 Byte) | 3 (0x03) 968 |Starting Address | (2 Bytes) | 0 - 65535 (0x0000 to 0xFFFF) 969 |Number of Registers | (2 Bytes) | 1 to 125 (0x7D) 970 |Checksum | (2 bytes) | Calculated automatically 971 |======================================== 972 973 974 Here is an example sent command as printed in the terminal (all Hex): + 975 ---- 976 INFO CLASSICLADDER- Modbus I/O module to send: Lgt=8 <- Slave address-1 Function code-3 Data-21 0 0 1 8E 36 977 ---- 978 meaning (Hex): + 979 980 * Lgt = 8 = message is 8 bytes long including slave number and checksum number + 981 * Slave number = 1 (0x1) = Slave address 1 982 * Function code = 3 (0x3) = read holding register 983 * Start at address = highbyte 33 (0x21) lowbyte 0 (0x00) = combined address = 8448 (0x2100) 984 * Number of Registers = 1 (0x1) = return 1 2-byte register (holding and reading registers are always 2 bytes wide) 985 * Checksum = high byte 0x8E lowbyte 0x36 = (0x8E36) 986 987 ==== Error response 988 If there is an error response, it sends the function code plus 0x80, an error code, and a checksum. + 989 Getting an error response means the slave is seeing the request command but can not give valid data. + 990 Looking in the Modbus protocol reference: + 991 992 .Error returned for function code 3 (read holding register) 993 994 [width="50%", options="header", cols="<6,<2,<6"] 995 |======================================== 996 |Name | number of bytes | Value (hex) 997 |Error code | 1 Byte | 131 (0x83) 998 |Exception code | 1 Byte | 1-4 (0x01 to 0x04) 999 |Checksum | (2 bytes) | Calculated automatically 1000 |======================================== 1001 1002 exception code meaning: 1003 1004 * 1 - illegal Function 1005 * 2 - illegal data address 1006 * 3 - illegal data value 1007 * 4 - slave device failure 1008 1009 Here is an example received command as printed in the terminal (all Hex): + 1010 ---- 1011 INFO CLASSICLADDER- Modbus I/O module received: Lgt=5 -> (Slave address-1 Function code-83 ) 2 C0 F1 1012 ---- 1013 meaning (Hex): + 1014 1015 * Slave number = 1 (0x1) = Slave address 1 1016 * Function code = 131 (0x83) = error while reading holding register 1017 * Error code = 2 (0x2) = illegal data address requested 1018 * Checksum = (0x8E36) 1019 1020 ==== Data response 1021 Looking in the Modbus protocol reference for Response: + 1022 1023 .Data response for function code 3 (read holding register) 1024 1025 [width="50%", options="header", cols="<6,<2,<6"] 1026 |======================================== 1027 |Name | number of bytes | Value (hex) 1028 |Function code | 1 Byte | 3 (0x03) 1029 |Byte count | 1 Byte | 2 x N* 1030 |Register value | N* x 2 Bytes | returned value of requested address 1031 |Checksum | (2 bytes) | Calculated automatically 1032 | ( *N = Number of Registers ) | | 1033 |======================================== 1034 1035 1036 Here is an example received command as printed in the terminal (all Hex): + 1037 ---- 1038 INFO CLASSICLADDER- Modbus I/O module received: Lgt=7 -> (Slave address-1 Function code-3 2 0 0 B8 44 1039 ---- 1040 1041 meaning (Hex): + 1042 1043 * Slave number = 1 (0x1) = Slave address 1 1044 * Requested function code = 3 (0x3) = read holding register requested 1045 * count of byte registers = 2 (0x1) = return 2 bytes (each register value is 2 bytes wide) 1046 * value of highbyte = 0 (0x0) = high byte value of address 8448 (0x2100) 1047 * value of lowbyte = 0 (0x0) = high byte value of address 8448 (0x2100) 1048 * Checksum = (0xB844) 1049 1050 (high and low bytes are combined to create a 16 bit value and then transferred to Classicladder's variable) + 1051 Read Registers can be mapped to %W or %QW (internal memory or HAL out pins) + 1052 Write registers can be mapped from %W, %QW or %IW (internal memory, HAL out pins or HAL in pins) + 1053 The variable number will start at the number entered in the modbus I/O registry setup page's column: 'First variable mapped' + 1054 If multiple registers are requested in one read/write then the variable number are sequential after the first one. + 1055 1056 === MODBUS Bugs 1057 1058 * In compare blocks the function %W=ABS(%W1-%W2) is accepted but does 1059 not compute properly. only %W0=ABS(%W1) is currently legal. 1060 * When loading a ladder program it will load Modbus info but will not 1061 tell Classic Ladder to initialize Modbus. You must initialize Modbus 1062 when you first load the GUI by adding '--modmaster'. 1063 * If the section manager is placed on top of the section display, across 1064 the scroll bar and exit is clicked the user program crashes. 1065 * When using '--modmaster' you must load the ladder program at the same 1066 time or else only TCP will work. 1067 * reading/writing multiple registers in Modbus has checksum errors. 1068 1069 == Setting up Classic Ladder 1070 1071 In this section we will cover the steps needed to add Classic Ladder 1072 to a Stepconf Wizard generated config. On the advanced Configuration 1073 Options page of Stepconf Wizard check off "Include Classic Ladder PLC". 1074 1075 .Stepconf Classic Ladder 1076 1077 image::images/stepconf_ladder.png[align="center", alt="Stepconf Classic Ladder"] 1078 1079 === Add the Modules 1080 1081 If you used the Stepconf Wizard to add Classic Ladder you can skip 1082 this step. 1083 1084 To manually add Classic Ladder you must first add the modules. This is 1085 done by adding a couple of lines to the custom.hal file. 1086 1087 This line loads the real time module: 1088 1089 ---- 1090 loadrt classicladder_rt 1091 ---- 1092 1093 This line adds the Classic Ladder function to the servo thread: 1094 1095 ---- 1096 addf classicladder.0.refresh servo-thread 1097 ---- 1098 1099 === Adding Ladder Logic 1100 1101 Now start up your config and select "File/Ladder Editor" to open up 1102 the Classic Ladder GUI. You should see a blank Section Display and 1103 Sections Manager window as shown above. In the Section Display window 1104 open the Editor. In the Editor window select Modify. Now a Properties 1105 window pops up and the Section Display shows a grid. The grid is one 1106 rung of ladder. The rung can contain branches. A simple rung has one 1107 input, a connector line and one output. A rung can have up to six 1108 horizontal branches. While it is possible to have more than one 1109 circuit in a run the results are not predictable. 1110 1111 .Section Display with Grid 1112 1113 image::images/Section_Display_Grid.png[align="center", alt="Section Display with Grid"] 1114 1115 Now click on the N.O. Input in the Editor Window. 1116 1117 .Editor Window 1118 1119 image::images/Editor_NO_Input.png[align="center", alt="Editor Window"] 1120 1121 Now click in the upper left grid to place the N.O. Input into the 1122 ladder. 1123 1124 .Section Display with Input 1125 1126 image::images/Section_Display_Build01.png[align="center", alt="Section Display with Input"] 1127 1128 Repeat the above steps to add a N.O. Output to the upper right grid 1129 and use the Horizontal Connection to connect the two. It should look 1130 like the following. If not, use the Eraser to remove unwanted sections. 1131 1132 .Section Display with Rung 1133 1134 image::images/Section_Display_Build02.png[align="center", alt="Section Display with Rung"] 1135 1136 Now click on the OK button in the Editor window. Now your Section 1137 Display should look like this. 1138 1139 .Section Display Finished 1140 1141 image::images/Section_Display_Build03.png[align="center", alt="Section Display Finished"] 1142 1143 To save the new file select Save As and give it a name. The .clp 1144 extension will be added automatically. It should default to the running 1145 config directory as the place to save it. 1146 1147 .Save As Dialog 1148 1149 image::images/SaveAs.png[align="center", alt="Save As Dialog"] 1150 1151 Again if you used the Stepconf Wizard to add Classic Ladder you can 1152 skip this step. 1153 1154 To manually add a ladder you need to add add a line to your custom.hal 1155 file that will load your ladder file. Close your LinuxCNC session and add 1156 this line to your custom.hal file. 1157 1158 ---- 1159 loadusr -w classicladder --nogui MyLadder.clp 1160 ---- 1161 1162 Now if you start up your LinuxCNC config your ladder program will be 1163 running as well. If you select "File/Ladder Editor", the program you 1164 created will show up in the Section Display window. 1165 1166