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)
    * 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 <Tab> 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
<Ctrl+M>. 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 <Ctrl+R>. 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