From f7669a3fcc87d4f6040257c3dd8708c263331458 Mon Sep 17 00:00:00 2001 From: Rr42 Date: Fri, 25 May 2018 10:13:59 +0530 Subject: Added all LDmicro filles to be ported --- ldmicro/manual.txt | 969 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 969 insertions(+) create mode 100644 ldmicro/manual.txt (limited to 'ldmicro/manual.txt') diff --git a/ldmicro/manual.txt b/ldmicro/manual.txt new file mode 100644 index 0000000..6d7d5e7 --- /dev/null +++ b/ldmicro/manual.txt @@ -0,0 +1,969 @@ + +INTRODUCTION +============ + +LDmicro generates native code for certain Microchip PIC16 and Atmel AVR +microcontrollers. Usually software for these microcontrollers is written +in a programming language like assembler, C, or BASIC. A program in one +of these languages comprises a list of statements. These languages are +powerful and well-suited to the architecture of the processor, which +internally executes a list of instructions. + +PLCs, on the other hand, are often programmed in `ladder logic.' A simple +program might look like this: + + || || + || Xbutton1 Tdon Rchatter Yred || + 1 ||-------]/[---------[TON 1.000 s]-+-------]/[--------------( )-------|| + || | || + || Xbutton2 Tdof | || + ||-------]/[---------[TOF 2.000 s]-+ || + || || + || || + || || + || Rchatter Ton Tnew Rchatter || + 2 ||-------]/[---------[TON 1.000 s]----[TOF 1.000 s]---------( )-------|| + || || + || || + || || + ||------[END]---------------------------------------------------------|| + || || + || || + +(TON is a turn-on delay; TOF is a turn-off delay. The --] [-- statements +are inputs, which behave sort of like the contacts on a relay. The +--( )-- statements are outputs, which behave sort of like the coil of a +relay. Many good references for ladder logic are available on the Internet +and elsewhere; details specific to this implementation are given below.) + +A number of differences are apparent: + + * The program is presented in graphical format, not as a textual list + of statements. Many people will initially find this easier to + understand. + + * At the most basic level, programs look like circuit diagrams, with + relay contacts (inputs) and coils (outputs). This is intuitive to + programmers with knowledge of electric circuit theory. + + * The ladder logic compiler takes care of what gets calculated + where. You do not have to write code to determine when the outputs + have to get recalculated based on a change in the inputs or a + timer event, and you do not have to specify the order in which + these calculations must take place; the PLC tools do that for you. + +LDmicro compiles ladder logic to PIC16 or AVR code. The following +processors are supported: + * PIC16F877 + * PIC16F628 + * PIC16F876 (untested) + * PIC16F88 (untested) + * PIC16F819 (untested) + * PIC16F887 (untested) + * PIC16F886 (untested) + * ATmega128 + * ATmega64 + * ATmega162 (untested) + * ATmega32 (untested) + * ATmega16 (untested) + * ATmega8 (untested) + +It would be easy to support more AVR or PIC16 chips, but I do not have +any way to test them. If you need one in particular then contact me and +I will see what I can do. + +Using LDmicro, you can draw a ladder diagram for your program. You can +simulate the logic in real time on your PC. Then when you are convinced +that it is correct you can assign pins on the microcontroller to the +program inputs and outputs. Once you have assigned the pins, you can +compile PIC or AVR code for your program. The compiler output is a .hex +file that you can program into your microcontroller using any PIC/AVR +programmer. + +LDmicro is designed to be somewhat similar to most commercial PLC +programming systems. There are some exceptions, and a lot of things +aren't standard in industry anyways. Carefully read the description +of each instruction, even if it looks familiar. This document assumes +basic knowledge of ladder logic and of the structure of PLC software +(the execution cycle: read inputs, compute, write outputs). + + +ADDITIONAL TARGETS +================== + +It is also possible to generate ANSI C code. You could use this with any +processor for which you have a C compiler, but you are responsible for +supplying the runtime. That means that LDmicro just generates source +for a function PlcCycle(). You are responsible for calling PlcCycle +every cycle time, and you are responsible for implementing all the I/O +(read/write digital input, etc.) functions that the PlcCycle() calls. See +the comments in the generated source for more details. + +Finally, LDmicro can generate processor-independent bytecode for a +virtual machine designed to run ladder logic code. I have provided a +sample implementation of the interpreter/VM, written in fairly portable +C. This target will work for just about any platform, as long as you +can supply your own VM. This might be useful for applications where you +wish to use ladder logic as a `scripting language' to customize a larger +program. See the comments in the sample interpreter for details. + + +COMMAND LINE OPTIONS +==================== + +ldmicro.exe is typically run with no command line options. That means +that you can just make a shortcut to the program, or save it to your +desktop and double-click the icon when you want to run it, and then you +can do everything from within the GUI. + +If LDmicro is passed a single filename on the command line +(e.g. `ldmicro.exe asd.ld'), then LDmicro will try to open `asd.ld', +if it exists. An error is produced if `asd.ld' does not exist. This +means that you can associate ldmicro.exe with .ld files, so that it runs +automatically when you double-click a .ld file. + +If LDmicro is passed command line arguments in the form +`ldmicro.exe /c src.ld dest.hex', then it tries to compile `src.ld', +and save the output as `dest.hex'. LDmicro exits after compiling, +whether the compile was successful or not. Any messages are printed +to the console. This mode is useful only when running LDmicro from the +command line. + + +BASICS +====== + +If you run LDmicro with no arguments then it starts with an empty +program. If you run LDmicro with the name of a ladder program (xxx.ld) +on the command line then it will try to load that program at startup. +LDmicro uses its own internal format for the program; it cannot import +logic from any other tool. + +If you did not load an existing program then you will be given a program +with one empty rung. You could add an instruction to it; for example +you could add a set of contacts (Instruction -> Insert Contacts) named +`Xnew'. `X' means that the contacts will be tied to an input pin on the +microcontroller. You could assign a pin to it later, after choosing a +microcontroller and renaming the contacts. The first letter of a name +indicates what kind of object it is. For example: + + * Xname -- tied to an input pin on the microcontroller + * Yname -- tied to an output pin on the microcontroller + * Rname -- `internal relay': a bit in memory + * Tname -- a timer; turn-on delay, turn-off delay, or retentive + * Cname -- a counter, either count-up or count-down + * Aname -- an integer read from an A/D converter + * name -- a general-purpose (integer) variable + +Choose the rest of the name so that it describes what the object does, +and so that it is unique within the program. The same name always refers +to the same object within the program. For example, it would be an error +to have a turn-on delay (TON) called `Tdelay' and a turn-off delay (TOF) +called `Tdelay' in the same program, since each counter needs its own +memory. On the other hand, it would be correct to have a retentive timer +(RTO) called `Tdelay' and a reset instruction (RES) associated with +`Tdelay', since it that case you want both instructions to work with +the same timer. + +Variable names can consist of letters, numbers, and underscores +(_). A variable name must not start with a number. Variable names are +case-sensitive. + +The general variable instructions (MOV, ADD, EQU, etc.) can work on +variables with any name. This means that they can access timer and +counter accumulators. This may sometimes be useful; for example, you +could check if the count of a timer is in a particular range. + +Variables are always 16 bit integers. This means that they can go +from -32768 to 32767. Variables are always treated as signed. You can +specify literals as normal decimal numbers (0, 1234, -56). You can also +specify ASCII character values ('A', 'z') by putting the character in +single-quotes. You can use an ASCII character code in most places that +you could use a decimal number. + +At the bottom of the screen you will see a list of all the objects in +the program. This list is automatically generated from the program; +there is no need to keep it up to date by hand. Most objects do not +need any configuration. `Xname', `Yname', and `Aname' objects must be +assigned to a pin on the microcontroller, however. First choose which +microcontroller you are using (Settings -> Microcontroller). Then assign +your I/O pins by double-clicking them on the list. + +You can modify the program by inserting or deleting instructions. The +cursor in the program display blinks to indicate the currently selected +instruction and the current insertion point. If it is not blinking then +press or click on an instruction. Now you can delete the current +instruction, or you can insert a new instruction to the right or left +(in series with) or above or below (in parallel with) the selected +instruction. Some operations are not allowed. For example, no instructions +are allowed to the right of a coil. + +The program starts with just one rung. You can add more rungs by selecting +Insert Rung Before/After in the Logic menu. You could get the same effect +by placing many complicated subcircuits in parallel within one rung, +but it is more clear to use multiple rungs. + +Once you have written a program, you can test it in simulation, and then +you can compile it to a HEX file for the target microcontroller. + + +SIMULATION +========== + +To enter simulation mode, choose Simulate -> Simulation Mode or press +. The program is shown differently in simulation mode. There is +no longer a cursor. The instructions that are energized show up bright +red; the instructions that are not appear greyed. Press the space bar to +run the PLC one cycle. To cycle continuously in real time, choose +Simulate -> Start Real-Time Simulation, or press . The display of +the program will be updated in real time as the program state changes. + +You can set the state of the inputs to the program by double-clicking +them in the list at the bottom of the screen, or by double-clicking an +`Xname' contacts instruction in the program. If you change the state of +an input pin then that change will not be reflected in how the program +is displayed until the PLC cycles; this will happen automatically if +you are running a real time simulation, or when you press the space bar. + + +COMPILING TO NATIVE CODE +======================== + +Ultimately the point is to generate a .hex file that you can program +into your microcontroller. First you must select the part number of the +microcontroller, under the Settings -> Microcontroller menu. Then you +must assign an I/O pin to each `Xname' or `Yname' object. Do this by +double-clicking the object name in the list at the bottom of the screen. +A dialog will pop up where you can choose an unallocated pin from a list. + +Then you must choose the cycle time that you will run with, and you must +tell the compiler what clock speed the micro will be running at. These +are set under the Settings -> MCU Parameters... menu. In general you +should not need to change the cycle time; 10 ms is a good value for most +applications. Type in the frequency of the crystal that you will use +with the microcontroller (or the ceramic resonator, etc.) and click okay. + +Now you can generate code from your program. Choose Compile -> Compile, +or Compile -> Compile As... if you have previously compiled this program +and you want to specify a different output file name. If there are no +errors then LDmicro will generate an Intel IHEX file ready for +programming into your chip. + +Use whatever programming software and hardware you have to load the hex +file into the microcontroller. Remember to set the configuration bits +(fuses)! For PIC16 processors, the configuration bits are included in the +hex file, and most programming software will look there automatically. +For AVR processors you must set the configuration bits by hand. + + +INSTRUCTIONS REFERENCE +====================== + +> CONTACT, NORMALLY OPEN Xname Rname Yname + ----] [---- ----] [---- ----] [---- + + If the signal going into the instruction is false, then the output + signal is false. If the signal going into the instruction is true, + then the output signal is true if and only if the given input pin, + output pin, or internal relay is true, else it is false. This + instruction can examine the state of an input pin, an output pin, + or an internal relay. + + +> CONTACT, NORMALLY CLOSED Xname Rname Yname + ----]/[---- ----]/[---- ----]/[---- + + If the signal going into the instruction is false, then the output + signal is false. If the signal going into the instruction is true, + then the output signal is true if and only if the given input pin, + output pin, or internal relay is false, else it is false. This + instruction can examine the state of an input pin, an output pin, + or an internal relay. This is the opposite of a normally open contact. + + +> COIL, NORMAL Rname Yname + ----( )---- ----( )---- + + If the signal going into the instruction is false, then the given + internal relay or output pin is cleared false. If the signal going + into this instruction is true, then the given internal relay or output + pin is set true. It is not meaningful to assign an input variable to a + coil. This instruction must be the rightmost instruction in its rung. + + +> COIL, NEGATED Rname Yname + ----(/)---- ----(/)---- + + If the signal going into the instruction is true, then the given + internal relay or output pin is cleared false. If the signal going + into this instruction is false, then the given internal relay or + output pin is set true. It is not meaningful to assign an input + variable to a coil. This is the opposite of a normal coil. This + instruction must be the rightmost instruction in its rung. + + +> COIL, SET-ONLY Rname Yname + ----(S)---- ----(S)---- + + If the signal going into the instruction is true, then the given + internal relay or output pin is set true. Otherwise the internal + relay or output pin state is not changed. This instruction can only + change the state of a coil from false to true, so it is typically + used in combination with a reset-only coil. This instruction must + be the rightmost instruction in its rung. + + +> COIL, RESET-ONLY Rname Yname + ----(R)---- ----(R)---- + + If the signal going into the instruction is true, then the given + internal relay or output pin is cleared false. Otherwise the + internal relay or output pin state is not changed. This instruction + instruction can only change the state of a coil from true to false, + so it is typically used in combination with a set-only coil. This + instruction must be the rightmost instruction in its rung. + + +> TURN-ON DELAY Tdon + -[TON 1.000 s]- + + When the signal going into the instruction goes from false to true, + the output signal stays false for 1.000 s before going true. When the + signal going into the instruction goes from true to false, the output + signal goes false immediately. The timer is reset every time the input + goes false; the input must stay true for 1000 consecutive milliseconds + before the output will go true. The delay is configurable. + + The `Tname' variable counts up from zero in units of scan times. The + TON instruction outputs true when the counter variable is greater + than or equal to the given delay. It is possible to manipulate the + counter variable elsewhere, for example with a MOV instruction. + + +> TURN-OFF DELAY Tdoff + -[TOF 1.000 s]- + + When the signal going into the instruction goes from true to false, + the output signal stays true for 1.000 s before going false. When + the signal going into the instruction goes from false to true, + the output signal goes true immediately. The timer is reset every + time the input goes false; the input must stay false for 1000 + consecutive milliseconds before the output will go false. The delay + is configurable. + + The `Tname' variable counts up from zero in units of scan times. The + TON instruction outputs true when the counter variable is greater + than or equal to the given delay. It is possible to manipulate the + counter variable elsewhere, for example with a MOV instruction. + + +> RETENTIVE TIMER Trto + -[RTO 1.000 s]- + + This instruction keeps track of how long its input has been true. If + its input has been true for at least 1.000 s, then the output is + true. Otherwise the output is false. The input need not have been + true for 1000 consecutive milliseconds; if the input goes true + for 0.6 s, then false for 2.0 s, and then true for 0.4 s, then the + output will go true. After the output goes true it will stay true + even after the input goes false, as long as the input has been true + for longer than 1.000 s. This timer must therefore be reset manually, + using the reset instruction. + + The `Tname' variable counts up from zero in units of scan times. The + TON instruction outputs true when the counter variable is greater + than or equal to the given delay. It is possible to manipulate the + counter variable elsewhere, for example with a MOV instruction. + + +> RESET Trto Citems + ----{RES}---- ----{RES}---- + + This instruction resets a timer or a counter. TON and TOF timers are + automatically reset when their input goes false or true, so RES is + not required for these timers. RTO timers and CTU/CTD counters are + not reset automatically, so they must be reset by hand using a RES + instruction. When the input is true, the counter or timer is reset; + when the input is false, no action is taken. This instruction must + be the rightmost instruction in its rung. + + +> ONE-SHOT RISING _ + --[OSR_/ ]-- + + This instruction normally outputs false. If the instruction's input + is true during this scan and it was false during the previous scan + then the output is true. It therefore generates a pulse one scan + wide on each rising edge of its input signal. This instruction is + useful if you want to trigger events off the rising edge of a signal. + + +> ONE-SHOT FALLING _ + --[OSF \_]-- + + This instruction normally outputs false. If the instruction's input + is false during this scan and it was true during the previous scan + then the output is true. It therefore generates a pulse one scan + wide on each falling edge of its input signal. This instruction is + useful if you want to trigger events off the falling edge of a signal. + + +> SHORT CIRCUIT, OPEN CIRCUIT + ----+----+---- ----+ +---- + + The output condition of a short-circuit is always equal to its + input condition. The output condition of an open-circuit is always + false. These are mostly useful for debugging. + + +> MASTER CONTROL RELAY + -{MASTER RLY}- + + By default, the rung-in condition of every rung is true. If a master + control relay instruction is executed with a rung-in condition of + false, then the rung-in condition for all following rungs becomes + false. This will continue until the next master control relay + instruction is reached (regardless of the rung-in condition of that + instruction). These instructions must therefore be used in pairs: + one to (maybe conditionally) start the possibly-disabled section, + and one to end it. + + +> MOVE {destvar := } {Tret := } + -{ 123 MOV}- -{ srcvar MOV}- + + When the input to this instruction is true, it sets the given + destination variable equal to the given source variable or + constant. When the input to this instruction is false nothing + happens. You can assign to any variable with the move instruction; + this includes timer and counter state variables, which can be + distinguished by the leading `T' or `C'. For example, an instruction + moving 0 into `Tretentive' is equivalent to a reset (RES) instruction + for that timer. This instruction must be the rightmost instruction + in its rung. + + +> ARITHMETIC OPERATION {ADD kay :=} {SUB Ccnt :=} + -{ 'a' + 10 }- -{ Ccnt - 10 }- + +> {MUL dest :=} {DIV dv := } + -{ var * -990 }- -{ dv / -10000}- + + When the input to this instruction is true, it sets the given + destination variable equal to the given expression. The operands + can be either variables (including timer and counter variables) + or constants. These instructions use 16 bit signed math. Remember + that the result is evaluated every cycle when the input condition + true. If you are incrementing or decrementing a variable (i.e. if + the destination variable is also one of the operands) then you + probably don't want that; typically you would use a one-shot so that + it is evaluated only on the rising or falling edge of the input + condition. Divide truncates; 8 / 3 = 2. This instruction must be + the rightmost instruction in its rung. + + +> COMPARE [var ==] [var >] [1 >=] + -[ var2 ]- -[ 1 ]- -[ Ton]- + +> [var /=] [-4 < ] [1 <=] + -[ var2 ]- -[ vartwo]- -[ Cup]- + + If the input to this instruction is false then the output is false. If + the input is true then the output is true if and only if the given + condition is true. This instruction can be used to compare (equals, + is greater than, is greater than or equal to, does not equal, + is less than, is less than or equal to) a variable to a variable, + or to compare a variable to a 16-bit signed constant. + + +> COUNTER Cname Cname + --[CTU >=5]-- --[CTD >=5]-- + + A counter increments (CTU, count up) or decrements (CTD, count + down) the associated count on every rising edge of the rung input + condition (i.e. what the rung input condition goes from false to + true). The output condition from the counter is true if the counter + variable is greater than or equal to 5, and false otherwise. The + rung output condition may be true even if the input condition is + false; it only depends on the counter variable. You can have CTU + and CTD instructions with the same name, in order to increment and + decrement the same counter. The RES instruction can reset a counter, + or you can perform general variable operations on the count variable. + + +> CIRCULAR COUNTER Cname + --{CTC 0:7}-- + + A circular counter works like a normal CTU counter, except that + after reaching its upper limit, it resets its counter variable + back to 0. For example, the counter shown above would count 0, 1, + 2, 4, 5, 6, 7, 0, 1, 2, 3, 4, 5, 6, 7, 0, 2,.... This is useful in + combination with conditional statements on the variable `Cname'; + you can use this like a sequencer. CTC counters clock on the rising + edge of the rung input condition condition. This instruction must + be the rightmost instruction in its rung. + + +> SHIFT REGISTER {SHIFT REG } + -{ reg0..3 }- + + A shift register is associated with a set of variables. For example, + this shift register is associated with the variables `reg0', `reg1', + `reg2', and `reg3'. The input to the shift register is `reg0'. On + every rising edge of the rung-in condition, the shift register will + shift right. That means that it assigns `reg3 := reg2', `reg2 := + reg1'. and `reg1 := reg0'. `reg0' is left unchanged. A large shift + register can easily consume a lot of memory. This instruction must + be the rightmost instruction in its rung. + + +> LOOK-UP TABLE {dest := } + -{ LUT[i] }- + + A look-up table is an ordered set of n values. When the rung-in + condition is true, the integer variable `dest' is set equal to the + entry in the lookup table corresponding to the integer variable + `i'. The index starts from zero, so `i' must be between 0 and + (n-1). The behaviour of this instruction is not defined if the + index is outside this range. This instruction must be the rightmost + instruction in its rung. + + +> PIECEWISE LINEAR TABLE {yvar := } + -{ PWL[xvar] }- + + This is a good way to approximate a complicated function or + curve. It might, for example, be useful if you are trying to apply + a calibration curve to convert a raw output voltage from a sensor + into more convenient units. + + Assume that you are trying to approximate a function that converts + an integer input variable, x, to an integer output variable, y. You + know the function at several points; for example, you might know that + + f(0) = 2 + f(5) = 10 + f(10) = 50 + f(100) = 100 + + This means that the points + + (x0, y0) = ( 0, 2) + (x1, y1) = ( 5, 10) + (x2, y2) = ( 10, 50) + (x3, y3) = (100, 100) + + lie on that curve. You can enter those 4 points into a table + associated with the piecewise linear instruction. The piecewise linear + instruction will look at the value of xvar, and set the value of + yvar. It will set yvar in such a way that the piecewise linear curve + will pass through all of the points that you give it; for example, + if you set xvar = 10, then the instruction will set yvar = 50. + + If you give the instruction a value of xvar that lies between two + of the values of x for which you have given it points, then the + instruction will set yvar so that (xvar, yvar) lies on the straight + line connecting those two points in the table. For example, xvar = + 55 gives an output of yvar = 75. (The two points in the table are + (10, 50) and (100, 100). 55 is half-way between 10 and 100, and 75 + is half-way between 50 and 100, so (55, 75) lies on the line that + connects those two points.) + + The points must be specified in ascending order by x coordinate. It + may not be possible to perform mathematical operations required for + certain look-up tables using 16-bit integer math; if this is the + case, then LDmicro will warn you. For example, this look up table + will produce an error: + + (x0, y0) = ( 0, 0) + (x1, y1) = (300, 300) + + You can fix these errors by making the distance between points in + the table smaller. For example, this table is equivalent to the one + given above, and it does not produce an error: + + (x0, y0) = ( 0, 0) + (x1, y1) = (150, 150) + (x2, y2) = (300, 300) + + It should hardly ever be necessary to use more than five or six + points. Adding more points makes your code larger and slower to + execute. The behaviour if you pass a value of `xvar' greater than + the greatest x coordinate in the table or less than the smallest x + coordinate in the table is undefined. This instruction must be the + rightmost instruction in its rung. + + +> A/D CONVERTER READ Aname + --{READ ADC}-- + + LDmicro can generate code to use the A/D converters built in to + certain microcontrollers. If the input condition to this instruction + is true, then a single sample from the A/D converter is acquired and + stored in the variable `Aname'. This variable can subsequently be + manipulated with general variable operations (less than, greater than, + arithmetic, and so on). Assign a pin to the `Axxx' variable in the + same way that you would assign a pin to a digital input or output, + by double-clicking it in the list at the bottom of the screen. If + the input condition to this rung is false then the variable `Aname' + is left unchanged. + + For all currently-supported devices, 0 volts input corresponds to + an ADC reading of 0, and an input equal to Vdd (the supply voltage) + corresponds to an ADC reading of 1023. If you are using an AVR, then + connect AREF to Vdd. You can use arithmetic operations to scale the + reading to more convenient units afterwards, but remember that you + are using integer math. In general not all pins will be available + for use with the A/D converter. The software will not allow you to + assign non-A/D pins to an analog input. This instruction must be + the rightmost instruction in its rung. + + +> SET PWM DUTY CYCLE duty_cycle + -{PWM 32.8 kHz}- + + LDmicro can generate code to use the PWM peripheral built in to + certain microcontrollers. If the input condition to this instruction + is true, then the duty cycle of the PWM peripheral is set to the + value of the variable duty_cycle. The duty cycle must be a number + between 0 and 100; 0 corresponds to always low, and 100 corresponds to + always high. (If you are familiar with how the PWM peripheral works, + then notice that that means that LDmicro automatically scales the + duty cycle variable from percent to PWM clock periods.) + + You can specify the target PWM frequency, in Hz. The frequency that + you specify might not be exactly achievable, depending on how it + divides into the microcontroller's clock frequency. LDmicro will + choose the closest achievable frequency; if the error is large then + it will warn you. Faster speeds may sacrifice resolution. + + This instruction must be the rightmost instruction in its rung. + The ladder logic runtime consumes one timer to measure the cycle + time. That means that PWM is only available on microcontrollers + with at least two suitable timers. PWM uses pin CCP2 (not CCP1) + on PIC16 chips and OC2 (not OC1A) on AVRs. + + +> MAKE PERSISTENT saved_var + --{PERSIST}-- + + When the rung-in condition of this instruction is true, it causes the + specified integer variable to be automatically saved to EEPROM. That + means that its value will persist, even when the micro loses + power. There is no need to explicitly save the variable to EEPROM; + that will happen automatically, whenever the variable changes. The + variable is automatically loaded from EEPROM after power-on reset. If + a variable that changes frequently is made persistent, then the + EEPROM in your micro may wear out very quickly, because it is only + good for a limited (~100 000) number of writes. When the rung-in + condition is false, nothing happens. This instruction must be the + rightmost instruction in its rung. + + +> UART (SERIAL) RECEIVE var + --{UART RECV}-- + + LDmicro can generate code to use the UART built in to certain + microcontrollers. On AVRs with multiple UARTs only UART1 (not + UART0) is supported. Configure the baud rate using Settings -> MCU + Parameters. Certain baud rates may not be achievable with certain + crystal frequencies; LDmicro will warn you if this is the case. + + If the input condition to this instruction is false, then nothing + happens. If the input condition is true then this instruction tries + to receive a single character from the UART. If no character is read + then the output condition is false. If a character is read then its + ASCII value is stored in `var', and the output condition is true + for a single PLC cycle. + + +> UART (SERIAL) SEND var + --{UART SEND}-- + + LDmicro can generate code to use the UARTs built in to certain + microcontrollers. On AVRS with multiple UARTs only UART1 (not + UART0) is supported. Configure the baud rate using Settings -> MCU + Parameters. Certain baud rates may not be achievable with certain + crystal frequencies; LDmicro will warn you if this is the case. + + If the input condition to this instruction is false, then nothing + happens. If the input condition is true then this instruction writes + a single character to the UART. The ASCII value of the character to + send must previously have been stored in `var'. The output condition + of the rung is true if the UART is busy (currently transmitting a + character), and false otherwise. + + Remember that characters take some time to transmit. Check the output + condition of this instruction to ensure that the first character has + been transmitted before trying to send a second character, or use + a timer to insert a delay between characters. You must only bring + the input condition true (try to send a character) when the output + condition is false (UART is not busy). + + Investigate the formatted string instruction (next) before using this + instruction. The formatted string instruction is much easier to use, + and it is almost certainly capable of doing what you want. + + +> FORMATTED STRING OVER UART var + -{"Pressure: \3\r\n"}- + + LDmicro can generate code to use the UARTs built in to certain + microcontrollers. On AVRS with multiple UARTs only UART1 (not + UART0) is supported. Configure the baud rate using Settings -> MCU + Parameters. Certain baud rates may not be achievable with certain + crystal frequencies; LDmicro will warn you if this is the case. + + When the rung-in condition for this instruction goes from false to + true, it starts to send an entire string over the serial port. If + the string contains the special sequence `\3', then that sequence + will be replaced with the value of `var', which is automatically + converted into a string. The variable will be formatted to take + exactly 3 characters; for example, if `var' is equal to 35, then + the exact string printed will be `Pressure: 35\r\n' (note the extra + space). If instead `var' were equal to 1432, then the behaviour would + be undefined, because 1432 has more than three digits. In that case + it would be necessary to use `\4' instead. + + If the variable might be negative, then use `\-3d' (or `\-4d' + etc.) instead. That will cause LDmicro to print a leading space for + positive numbers, and a leading minus sign for negative numbers. + + If multiple formatted string instructions are energized at once + (or if one is energized before another completes), or if these + instructions are intermixed with the UART TX instructions, then the + behaviour is undefined. + + It is also possible to use this instruction to output a fixed string, + without interpolating an integer variable's value into the text that + is sent over serial. In that case simply do not include the special + escape sequence. + + Use `\\' for a literal backslash. In addition to the escape sequence + for interpolating an integer variable, the following control + characters are available: + * \r -- carriage return + * \n -- newline + * \f -- formfeed + * \b -- backspace + * \xAB -- character with ASCII value 0xAB (hex) + + The rung-out condition of this instruction is true while it is + transmitting data, else false. This instruction consumes a very + large amount of program memory, so it should be used sparingly. The + present implementation is not efficient, but a better one will + require modifications to all the back-ends. + + +A NOTE ON USING MATH +==================== + +Remember that LDmicro performs only 16-bit integer math. That means +that the final result of any calculation that you perform must be an +integer between -32768 and 32767. It also mean that the intermediate +results of your calculation must all be within that range. + +For example, let us say that you wanted to calculate y = (1/x)*1200, +where x is between 1 and 20. Then y goes between 1200 and 60, which +fits into a 16-bit integer, so it is at least in theory possible to +perform the calculation. There are two ways that you might code this: +you can perform the reciprocal, and then multiply: + + || {DIV temp :=} || + ||---------{ 1 / x }----------|| + || || + || {MUL y := } || + ||----------{ temp * 1200}----------|| + || || + +Or you could just do the division directly, in a single step: + + || {DIV y :=} || + ||-----------{ 1200 / x }-----------|| + +Mathematically, these two are equivalent; but if you try them, then you +will find that the first one gives an incorrect result of y = 0. That +is because the variable `temp' underflows. For example, when x = 3, +(1 / x) = 0.333, but that is not an integer; the division operation +approximates this as temp = 0. Then y = temp * 1200 = 0. In the second +case there is no intermediate result to underflow, so everything works. + +If you are seeing problems with your math, then check intermediate +results for underflow (or overflow, which `wraps around'; for example, +32767 + 1 = -32768). When possible, choose units that put values in +a range of -100 to 100. + +When you need to scale a variable by some factor, do it using a multiply +and a divide. For example, to scale y = 1.8*x, calculate y = (9/5)*x +(which is the same, since 1.8 = 9/5), and code this as y = (9*x)/5, +performing the multiplication first: + + || {MUL temp :=} || + ||---------{ x * 9 }----------|| + || || + || {DIV y :=} || + ||-----------{ temp / 5 }-----------|| + +This works for all x < (32767 / 9), or x < 3640. For larger values of x, +the variable `temp' would overflow. There is a similar lower limit on x. + + +CODING STYLE +============ + +I allow multiple coils in parallel in a single rung. This means that +you can do things like this: + + || Xa Ya || + 1 ||-------] [--------------( )-------|| + || || + || Xb Yb || + ||-------] [------+-------( )-------|| + || | || + || | Yc || + || +-------( )-------|| + || || + +Instead of this: + + || Xa Ya || + 1 ||-------] [--------------( )-------|| + || || + || || + || || + || || + || Xb Yb || + 2 ||-------] [--------------( )-------|| + || || + || || + || || + || || + || Xb Yc || + 3 ||-------] [--------------( )-------|| + || || + +This means that in theory you could write any program as one giant rung, +and there is no need to use multiple rungs at all. In practice that +would be a bad idea, because as rungs become more complex they become +more difficult to edit without deleting and redrawing a lot of logic. + +Still, it is often a good idea to group related logic together as a single +rung. This generates nearly identical code to if you made separate rungs, +but it shows that they are related when you look at them on the ladder +diagram. + + * * * + +In general, it is considered poor form to write code in such a way that +its output depends on the order of the rungs. For example, this code +isn't very good if both Xa and Xb might ever be true: + + || Xa {v := } || + 1 ||-------] [--------{ 12 MOV}--|| + || || + || Xb {v := } || + ||-------] [--------{ 23 MOV}--|| + || || + || || + || || + || || + || [v >] Yc || + 2 ||------[ 15]-------------( )-------|| + || || + +I will break this rule if in doing so I can make a piece of code +significantly more compact, though. For example, here is how I would +convert a 4-bit binary quantity on Xb3:0 into an integer: + + || {v := } || + 3 ||-----------------------------------{ 0 MOV}--|| + || || + || Xb0 {ADD v :=} || + ||-------] [------------------{ v + 1 }-----------|| + || || + || Xb1 {ADD v :=} || + ||-------] [------------------{ v + 2 }-----------|| + || || + || Xb2 {ADD v :=} || + ||-------] [------------------{ v + 4 }-----------|| + || || + || Xb3 {ADD v :=} || + ||-------] [------------------{ v + 8 }-----------|| + || || + +If the MOV statement were moved to the bottom of the rung instead of the +top, then the value of v when it is read elsewhere in the program would +be 0. The output of this code therefore depends on the order in which +the instructions are evaluated. Considering how cumbersome it would be +to code this any other way, I accept that. + + +BUGS +==== + +LDmicro does not generate very efficient code; it is slow to execute, and +wasteful of flash and RAM. In spite of this, a mid-sized PIC or AVR can +do everything that a small PLC can, so this does not bother me very much. + +The maximum length of variable names is highly limited. This is so that +they fit nicely onto the ladder diagram, so I don't see a good solution +to that. + +If your program is too big for the time, program memory, or data memory +constraints of the device that you have chosen then you probably won't +get an error. It will just screw up somewhere. + +Careless programming in the file load/save routines probably makes it +possible to crash or execute arbitrary code given a corrupt or malicious +.ld file. + +Please report additional bugs or feature requests to the author. + +Thanks to: + * Marcelo Solano, for reporting a UI bug under Win98 + * Serge V. Polubarjev, for not only noticing that RA3:0 on the + PIC16F628 didn't work but also telling me how to fix it + * Maxim Ibragimov, for reporting and diagnosing major problems + with the till-then-untested ATmega16 and ATmega162 targets + * Bill Kishonti, for reporting that the simulator crashed when the + ladder logic program divided by zero + * Mohamed Tayae, for reporting that persistent variables were broken + on the PIC16F628 + * David Rothwell, for reporting several user interface bugs and a + problem with the "Export as Text" function + + +COPYING, AND DISCLAIMER +======================= + +DO NOT USE CODE GENERATED BY LDMICRO IN APPLICATIONS WHERE SOFTWARE +FAILURE COULD RESULT IN DANGER TO HUMAN LIFE OR DAMAGE TO PROPERTY. THE +AUTHOR ASSUMES NO LIABILITY FOR ANY DAMAGES RESULTING FROM THE OPERATION +OF LDMICRO OR CODE GENERATED BY LDMICRO. + +This program is free software: you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation, either version 3 of the License, or (at your +option) any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see . + + +Jonathan Westhues + +Rijswijk -- Dec 2004 +Waterloo ON -- Jun, Jul 2005 +Cambridge MA -- Sep, Dec 2005 + Feb, Mar 2006 + Feb 2007 +Seattle WA -- Feb 2009 + +Email: user jwesthues, at host cq.cx + + -- cgit