# &microbe;

## Introduction and General Syntax

Microbe compiles programs written in the custom language for PICs, as a companion program to &kappname;. The syntax has been designed to suit a &flowcode; program.

The syntax for running `microbe` from the commandline is:

    microbe [options] [input.microbe] [output.asm]

where options are:

- `--show-source` - Puts each line of &microbe; source code as a comment in the assembly output before the assembly instructions themselves for that line.

- `--no-optimize` - Prevent optimization of the instructions generated from the source. Optimization is usually safe, and so this option is mainly used for debugging.

The .microbe input file must identify the target PIC by inserting the PIC name at the top of the .microbe file; e.g. the name of a PIC16F84 is "P16F84".

### Simple complete &microbe; program

    P16F84

    a = 0
    repeat
    {
    	PORTA = a
    	a = a + 1
    }
    until a == 5

    end

### Naming conventions

The following rules apply to variable names and labels:

- They can only contain alphanumerical characters [a..z][A..Z][0..9] and the underscore "_".

- They are case-sensitive.

- They cannot start with a number.

- They should not start with "__" (double underscore), as this is reserved for use by the compiler.

### Bracing conventions

Curly braces, {}, indicate the start and end of a code block.

They can appear anywhere before the start and after the end of the code block.

Examples of acceptable code blocks:

    statement1 {
    	some code
    }

    statement2 {
    	other code }

    statement3
    {
    	other code
    }

    statement5 {
    	code block
    } statement6

### Commenting

Commenting is similar to C. // comments out the rest of the line. /* and */ denote a multiline comment.

    // This is a comment
    x = 2
    /* As is this
    multiline comment */

### Program Structure

The PIC id must be inserted at the top of the program. The end of the main program is denoted with "end". Subroutines must placed after "end".

### Subroutines

A subroutine can be called from anywhere in the code. Syntax:

    sub SubName
    {
    	// Code...
    }

The subroutine is called with "call SubName".

## &microbe; language reference

### if

Conditional branching.

Syntax:

    if [expression] then [statement]

or

    if [expression] then
    {
    	[statement block]
    }

Similarly for else:

    else [statement]

or

    else
    {
    	[statement block]
    }

#### if

    if porta.0 is high then
    {
    	delay 200
    }
    else
    {
    	delay 300
    }

### alias

Aliases one string to another. Syntax:

    alias [from] [to]

### repeat

Executes the statement block repeatedly until expression evaluates to true.

The evaluation of the expression is performed after the statement block, so the statement block will always be executed at least once. Syntax:

    repeat
    {
    	[statement block]
    }
    until [expression]

### while

Similar to repeat, this repeatedly executes the statement block. However, the expression is evaluated before execution, not after. So if the expression evaluates to false on the first pass, then the statement block will not get executed.

Syntax:

    while [expression]
    {
    	[statement block]
    }

### goto

This causes execution of the code to continue at the next statement after the label specified.

Goto syntax:

    goto [labelname]

Label syntax:

    labelname:

It is often considered good programming practice to avoid the use of goto. Use of control statements and subroutines will result in a much more readable program.

#### goto

    goto MyLabel

    ...

    [MyLabel]:
    // Code will continue at this point

### call

Calls a subroutine.

Syntax:

    call [SubName]

where SubName is the name of the subroutine to be called.

### delay

This causes the code execution to stop for the given period of time. The interval is in milliseconds.

Syntax:

    delay [interval]

At present, &microbe; assumes that the PIC is operating at a frequency of 4Mhz - i.e. each instruction takes 1 microsecond to execute. If this is not the case, the interval must be adjusted proportionately.

### sevenseg

This is used to define the pin mapping for a (common cathode) seven segment display connected to the PIC. Syntax:

    sevenseg [name] [a] [b] [c] [d] [e] [f] [g]

where [a]...[g] are the PIC pins to which the respective segments of the seven segment display are attached. The pins can be written either as PORTX.N or RXN.

To display a number on the seven segment, the pin mapping is treated as a write only variable.

#### Defining and outputting to a seven segment

    sevenseg seg1 RB0 RB1 RB2 RB3 RB4 RB5 RB6
    seg1 = x + 2

### keypad

This is used to define the pin mapping for a keypad connected to the PIC. Syntax:

    keypad [name] [row 1] ... [row 4] [column 1] ... [column n]

where [row 1] ... [row 4] and [column 1] ... [column n] are the PIC pins to which the respective rows and columns of the keypad are attached (at the moment, the number of rows is not changeable). See (above) for more information on pin mappings.

The columns of the keypad should be pulled down via 100k resistors to ground. The row pins must be configured as outputs and the column pins as inputs. Once the keypad has been defined, it is treated as a read only variable.

#### Defining and reading from a keypad

    keypad keypad1 RB0 RB1 RB2 RB3 RB4 RB5 RB6
    x = keypad1

By default, the values returned for a keypad are:

- The value of the number if it is a numeric key (1 to 3 along top row; hexadecimal A to D down the fourth column and continuing for each extra column).

- 253 for the key in row 4, column 1.

- 254 for the key in row 4, column 3.

These values can be redefined by using the alias command, where the name of the key in row x, column y (rows and columns starting at 1), is Keypad_x_y. For example, to give the star key on a 4x3 keypad the value zero, the following alias would be used:

#### Aliasing a keypad key to a value

    alias Keypad_4_1 0

## PIC I/O

### Port Direction

The port direction is set by assigning a value to TRIS*, where * is the port letter. For example:

#### Setting port directions

    TRISB = b'01111001'

The above sets pins RB1, RB2 and RB7 on PORTB as outputs, and the other pins on PORTB as inputs. In this example, b'01111001' is a binary representation of the output type. The 1 on the right represents an output on RB0, and the 0 on the left represents an input on RB7.

### Port I/O

The port can be treated as a variable. For example:

#### Writing to a port

    x = PORTA

The above assigns the value of PORTA to the variable x.

### Pin I/O

Each pin on a port is obtained by prefixing the pin number by the port name; e.g. Pin 2 (starting from Pin 0) on PORTA is known as PORTA.0.

The syntax to set a pin state is:

    PORTX.N = STATE

where STATE can be high or low.

The syntax to test a pin state is:

    if PORTX.N is STATE then

Combining these examples, we have:

#### Setting and testing pin state

    TRISA = 0
    TRISB = 255
    if PORTA.3 is high then
    {
    	PORTB.5 = low
    }
    else
    {
    	PORTB = PORTA + 15
    }

## Variables

All variables are 8-bit unsigned integers, giving a range from 0 to 255.

&microbe; supports the typical unary operations (acting on one variable) and binary operations (acting on two variables) that are supported by the PIC. In addition, &microbe; also supports division and multiplication.

### Unary Operations

- rotateleft x - Rotates the variable x left through carry.

- rotateright x - Rotates the variable x right through carry.

- increment x - Increments the variable x. If x has a value of 255, then x wraps round to 0.

- decrement x - Decrements the variable x. If x has a value of 0, then x wraps round to 255.

### Arithmetic

Supported operations:

- Addition: x + y

- Subtraction: x - y

- Multiplication: x * y

- Division: x / y

- Binary XOR: x XOR y

- Binary AND: x AND y

- Binary OR: x OR y

### Comparison

Supported operations:

- Equals: x == y

- Does not equal: x != y

- Is greater than: x > y

- Is less than: x < y

- Is greater than or equal to: x >= y

- Is less than or equal to: x <= y

For example:

#### Comparison

    if PORTA >= 5 then
    {
    	...
    }