MecScript Language

MecScript is a statically-typed, heap-less, C-style scripting language for 32-bit embedded systems. Source files (.mec) compile to a compact bytecode binary (.mbin) that runs on a stack-based virtual machine inside the host device.

1. Program Structure

There is no main function. Top-level statements execute in source order when the script runs.

int x = 40;
int y = 2;
System::PrintInt(x + y);   // 42

System:: is the namespace host (native) functions are called through by default. A host can put its natives in a namespace of its own instead. See Native functions.

Functions and classes may be declared at the top level. They can be referenced before their declaration appears in the file (see Forward references).

2. Comments

MecScript supports C-style single line and block comments.

// Line comment.

/* Block
   comment. */

3. Types

MecScript is a statically typed language. All data types are known at compile time, making execution faster and safer.

The alias column is just another way to declare the same keyword: s8 and char compile to exactly the same type, so they mix freely and error messages always report the char/byte/… name.
Aliases are provided for convenience as they are a little more descriptive than the classical type names.

// These two data types are the same and both compile as "short"
short var1 = 0; // 16 bit signed integer
s16 var2 = 0;   // 16 bit signed integer

char and byte are numeric types, not a distinct character type. Individual character literals are not supported, so an integer must be used.

char c = 'a';  // Compile error
char c = 0x61; // OK

string is a reference to a compile-time constant. String variables and string native parameters can only ever hold a literal or another string constant. For mutable text, use a byte array (see Strings).

4. Literals

int   a = 42;        // decimal
int   b = 0xFF;      // hex
int   c = 0b1010;    // binary
int   d = 0o377;     // octal
float e = 3.14;      // float (a decimal point makes it a float)
bool  f = true;
bool  g = false;

null, NULL, and nil are all accepted and evaluate to integer 0.

String literals use double quotes. There are no escape sequences: "\n" is a backslash followed by n, not a newline.

System::PrintLine("Hello, world");

5. Variables

int count = 0;       // explicit initializer
int total;           // zero-initialized

All variables are zero-initialized if no initializer is given.

Scope

• Variables declared at the top level are globals.
• Variables declared inside a function or block are locals.
• Blocks ({ ... }) introduce a new scope. A local is visible from its declaration to the end of its enclosing block.

int g = 1;           // global

void f() {
    int local = 2;   // local to f
    {
        int inner = 3;   // local to this block only
    }
    // inner is not visible here
}

const

const marks a variable read-only after its initializer runs. Writing to it later is a compile error.

const int LIMIT = 100;
LIMIT = 200;         // compile error: Cannot write to const variable after initialisation.

Naming Style

MecScript enforces no naming convention. One common pattern is UpperCamelCase for functions and global variables and lowerCamelCase for locals and parameters, which makes a name’s scope visible at a glance and matches how the native reference set is written. The compiler accepts any style, and the choice is entirely yours.

6. Operators

All basic mathematical and bitwise operations are supported.

Arithmetic

a + b       // add
a - b       // subtract
a * b       // multiply
a / b       // divide
a % b       // modulus (remainder)

Bitwise

a & b       // bitwise AND
a | b       // bitwise OR
a ^ b       // bitwise XOR
~a          // bitwise NOT (ones complement)
a << b      // shift left
a >> b      // shift right

Comparison

a == b      // equal
a != b      // not equal
a < b       // less than
a > b       // greater than
a <= b      // less than or equal
a >= b      // greater than or equal

A comparison always produces a bool.

Logical

a && b      // logical AND
a || b      // logical OR
!a          // logical NOT

Assignment

a = b       // assign
a += b      // add and assign
a -= b      // subtract and assign
a *= b      // multiply and assign
a /= b      // divide and assign
a &= b      // bitwise AND and assign
a |= b      // bitwise OR and assign
a ^= b      // bitwise XOR and assign

There is no %=, <<=, or >>=.

Increment / Decrement

Both prefix and postfix forms work on a variable:

i++;        // postfix increment
++i;        // prefix increment
i--;        // postfix decrement
--i;        // prefix decrement

Narrow types wrap at their own width:

byte b = 255;
b++;                 // b is now 0

Ternary

Behaves like a single line if/else statement.

int max = (a > b) ? a : b;

// Is equivalent to:
int max;
if (a > b)
    max = a;
else
    max = b;

Precedence

From tightest to loosest binding:

1. . [] () (member, index, call)
2. ! ~ ++ -- (unary)
3. * / %
4. + - & | ^ << >>
5. < > <= >=
6. == !=
7. &&
8. ||
9. ?: (ternary)
10. = += -= *= /= (assignment)

Note that the bitwise and shift operators sit at the same level as + and -. Parenthesize when mixing them with arithmetic.

7. Type Conversions

Numeric types convert implicitly across signed, unsigned, and float categories as needed by an assignment, argument, or operator. There is no explicit cast syntax.

int   i = 10;
float f = i;         // int -> float
int   j = f / 4.0;   // float -> int on assignment

There is no integer overflow or wraparound detection. Arithmetic that exceeds a type’s range wraps silently.

8. Control Flow

if / else if / else

if (x > 0) {
    System::PrintInt(1);
} else if (x < 0) {
    System::PrintInt(-1);
} else {
    System::PrintInt(0);
}

while

A while loop will continue as long as the condition is true. There is no do/while.

int i = 0;
while (i < 5) {
    System::PrintInt(i);
    i++;
}

for

A for loop has an initializer, condition, and update expression. The loop will continue as long as the condition is true.

for (initializer, condition, update) { ... }

for (int i = 0; i < 10; i++) {
    System::PrintInt(i);
}

All three clauses are optional. Any of them may be left empty, and for (;;) is an infinite loop.

int i = 0;
for (; i < 10;) {        // no initializer, no post-expression
    System::PrintInt(i);
    i++;
}

for (;;) {               // infinite loop; exit with break
    if (done()) {
        break;
    }
}

break & continue

• continue will skip the rest of the loop body and continue to the next loop iteration.
• break exits the loop immediately.

break and continue work in while and for loops.

for(int i = 0; i < 10; i++) {
    if (i == 5) {
        break;
    }
    if (i % 2 == 0) {
        continue;
    }
    // do work...
}

switch

The controlling expression is an integer (float is rejected). case labels are integer literals and must be unique. default is optional. A case without a break falls through to the next case, as in C.

switch (code) {
    case 1:
        System::PrintLine("one");
        break;
    case 2:
        System::PrintLine("two");
        break;
    default:
        System::PrintLine("other");
        break;
}

A case with no body falls straight into the next one, which is how several values share a single handler:

switch (key) {
    case 1:
    case 2:
    case 3:
        System::PrintLine("low");      // runs for key 1, 2, or 3
        break;
    case 4:
        System::PrintLine("four");
        break;
}

A case that has a body but no break runs its own body and then continues into the next case:

switch (n) {
    case 1:
        System::PrintInt(1);           // no break: falls through
    case 2:
        System::PrintInt(2);
        break;
    case 3:
        System::PrintInt(3);
        break;
}
// n == 1 prints 1 then 2
// n == 2 prints 2
// n == 3 prints 3

A switch statement has to produce a jump table entry for every value between its lowest and highest case label value. This means that for large value ranges with a low number of case labels, the compiled output will be huge compared to if/else. The number of case labels has no effect on performance. The compiler will output a warning if the number of case labels is less than half the value range.

// Very fast, small/tight binary.
// Generates ~4 jump table entries
switch(input) {
    case 1: //...
    case 2: //...
    case 3: //...
    case 4: //...
}

// Very fast, very bloated binary.
// Generates ~300 jump table entries. Compiler warning.
switch(input) {
    case 100: //...
    case 200: //...
    case 300: //...
    case 400: //...
}

// Slower (must evaluate every condition until a match is found), minimal binary size.
if (input == 100) {
    //...
} else if (input == 200) {
    //...
} else if (input == 300) {
    //...
} else if (input == 400) {
    //...
}

9. Functions

int add(int a, int b) {
    return a + b;
}

void greet() {
    System::PrintLine("hi");
}

System::PrintInt(add(3, 4));   // 7
greet();

• Scalar parameters are passed by value.
• A non-void function must return a value.
• Calling with the wrong number of arguments is a compile error.
• Recursion is supported.

Forward References

A top-level function or class may be used before it is declared in the file. This allows mutual recursion:

bool isEven(int n) {
    if (n == 0) { return true; }
    return isOdd(n - 1);
}

bool isOdd(int n) {
    if (n == 0) { return false; }
    return isEven(n - 1);
}

System::PrintInt(isEven(10));  // 1

Array Parameters

An array parameter is written T name[] or T *name (equivalent). The array size is not carried in the type itself, so the caller still passes the array by bare name plus an explicit length argument, and should not rely on count/len matching the array’s real size. A variable index used inside the function is checked at runtime against the caller’s actual array, the same as any other array (see “Bounds checking” in the Arrays section); only a native function’s own C++ implementation is unchecked, C snprintf-style.

int sum(int values[], int count) {
    int total = 0;
    for (int i = 0; i < count; i++) {
        total += values[i];
    }
    return total;
}

int data[4] = {1, 2, 3, 4};
System::PrintInt(sum(data, 4));    // 10

Passing a non-array where an array parameter is expected, or an array of the wrong element type, is a compile error. So is giving the parameter a size (int values[4]).

Inside the function the parameter is used exactly like an array: index it, or pass it on by name to another array parameter, script or native. It cannot be used as a value on its own.

void send(byte data[], int length) {
    System::SendCanMessage(0, 0x100, data, length);
}

Class parameters

See Classes.

10. Arrays

int arr[5] = {10, 20, 30, 40, 50};
int zero[8];                 // all elements 0

• Array size is fixed at compile time.
• If an initializer list is present, its length must match the declared size exactly. int a[3] = {1, 2}; is a compile error.
• Without an initializer, every element is zero.

Indexing and assignment

System::PrintInt(arr[0]);      // 10
arr[2] = 99;
arr[2] += 1;         // 100

Packed storage

char/byte arrays pack 4 elements per 4-byte slot; short/ushort arrays pack 2 per slot. This is transparent to the script; index them normally.

byte buf[16];        // 4 slots
buf[0] = 1;
buf[15] = 200;

Bounds checking

A literal out-of-range index is a compile error, including a negative one:

byte b[8];
b[8] = 1;             // compile error: index 8 is out of bounds for 'b' (size 8)
b[-1] = 1;            // compile error

A variable or computed index is checked at runtime instead. An out-of-range access halts the VM with vmArrayIndexOutOfBounds rather than reading or writing whatever happens to sit next to the array:

byte b[8];
int i = 8;
b[i] = 1;             // halts with vmArrayIndexOutOfBounds

This covers array parameters too: a function indexing a T name[] parameter with a variable index is checked against the size of whatever array the caller actually passed in, even through several levels of forwarding. It also covers an array field declared inside a class, however it’s reached: directly, through a class-typed parameter, or through a composed/embedded instance. It never applies inside a native function’s own implementation, which reads and writes the buffer directly in host C++ with no VM involvement at all.

Bare array references

An array name used without an index has no value. It cannot be assigned to a scalar, returned as a scalar, or passed as a scalar argument. Pass it only to an array parameter (with a length) or index it.

int arr[3] = {10, 20, 30};
int x = arr;         // compile error

11. Strings

String literals are immutable compile-time constants. Use them directly with the print natives:

System::Print("no newline");
System::PrintLine("with newline");

For text you need to build or modify at runtime, use a byte buffer and the string natives. Every string native takes an explicit capacity, C snprintf-style. Nothing grows a buffer for you.

byte msg[32];
System::StrCopy(msg, 32, "Value: ");
byte num[16];
System::IntToStr(num, 16, 42);
// (append num's characters via StrAppend from a string constant only;
//  buffer-to-buffer append is not supported)
System::StrAppend(msg, 32, "42");
System::PrintBuffer(msg, 32);        // Value: 42
System::PrintInt(System::StrLength(msg, 32));  // 8

Notes and limits:

• StrCopy / StrAppend take a string constant as the source, not another byte[] buffer.
• A freshly declared buffer is zero-filled, so StrLength on an untouched buffer is 0.
• Content that does not fit the capacity is truncated and null-terminated.

12. Classes

Classes are supported for advanced data structures.

class Point {
    int x;
    int y;

    Point(int px, int py) {
        this.x = px;
        this.y = py;
    }

    int sum() {
        return this.x + this.y;
    }

    void shift(int dx, int dy) {
        x += dx;         // 'this.' is optional inside a method
        y += dy;
    }
}

Point p(1, 2);
System::PrintInt(p.sum());         // 3
p.shift(10, 10);
System::PrintInt(p.sum());         // 23

Fields

Declared in the class body. Each instance gets its own copy.

Methods

• Inside a method, this.field and a bare field name both refer to the current instance’s field.
• A method can call a sibling method on the same instance with this.method().

class Calculator {
    int total;

    Calculator(int start) { this.total = start; }

    void addFive() { this.total += 5; }

    void addTen() {
        this.addFive();
        this.addFive();
    }

    int get() { return this.total; }
}

Constructors

ClassName(params) { ... }. A class has at most one constructor. It runs when an instance is declared with an argument list:

Counter c(10);       // runs Counter(int)

Fields are always zero-initialized first, before the constructor body runs. A class with no constructor is declared without parentheses:

Counter d;           // no constructor; fields are 0

Declaring an instance of a class that has a constructor without an argument list compiles, but produces a warning.

Destructors

~ClassName() { ... }. Runs automatically when the instance goes out of scope:

• A local instance is destroyed at the end of its enclosing block.
• Multiple instances in the same scope are destroyed in reverse declaration order (LIFO).
• Global instances are destroyed once, at script end, in reverse declaration order.

class Noisy {
    int id;
    Noisy(int i) { this.id = i; }
    ~Noisy() { System::PrintInt(this.id); }
}

void test() {
    Noisy n(42);
    System::PrintInt(1);
}

test();              // prints 1 then 42
System::PrintInt(2);

Passing instances

Pass an instance to a function or method by reference with ClassName *param. The callee can call methods on it and read or write its fields, including compound assignment.

void bump(Counter *c) {
    c.increment();
}

Counter a(5);
bump(a);             // a.value is now 6

Passing an instance of the wrong class, or a non-instance, is a compile error. A bare instance name (no ., no method call, not passed to a class parameter) has no value and cannot be used as one.

Class-typed fields (composition)

A field may itself be a class instance. The embedded instance is laid out inline in its owner and reached with a chain of .:

class Inner {
    int value;
    void bump() { value += 100; }
}

class Outer {
    Inner inner;
    int count;

    void run() {
        this.inner.bump();      // method call on an embedded instance
        inner.bump();           // 'this.' is optional, same as any field
    }
}

Outer o;
o.inner.value = 900;           // read / write an embedded field
o.count = 4;
o.run();
System::PrintInt(o.inner.value);         // 1100

• Nesting is unlimited: a.b.c.x resolves as long as each step names a class-typed field.
• Compound assignment works through the chain: o.inner.value += 50;.
• An embedded instance can be passed by reference like any other instance: take(o.inner); where take takes Inner *i.
• When an instance is created, each embedded field is zero-initialized and its field-default initializers run, outermost first.
• Destructors run automatically and in order: the owner’s destructor body first, then each embedded field’s destructor in reverse declaration order.

Limits:

• No member-initializer syntax. You cannot pass constructor arguments to an embedded field. Embedding a class whose constructor takes arguments is a compile error. A class with no constructor (or a parameterless one) is fine.
• No cycles. A class cannot contain itself, directly or indirectly (class A { A a; }, or A holding a B that holds an A). This is a compile error.

Not supported

• Inheritance. Every class is standalone. There is no subclassing.
• Class-typed return values. A function cannot return a class instance.

13. Namespaces

Namespaces are optional. They group top-level declarations under a name so they can be kept tidy and referred to explicitly. They have no runtime cost or effect: a namespaced global is still a plain global, and a namespaced function is still an ordinary function.

namespace Geometry {
    int gridSize = 16;

    int area(int w, int h) {
        return w * h;
    }

    class Point {
        int x;
        int y;
        int sum() { return x + y; }
    }
}

Refer to a member from outside with the :: scope operator:

Geometry::gridSize = 32;
System::PrintInt(Geometry::area(3, 4));   // 12

Geometry::Point p;
p.x = 1;
p.y = 2;
System::PrintInt(p.sum());                 // 3

• Unqualified access inside the block. Within namespace Geometry { }, other members are visible without the prefix (area() can call gridSize and Point directly). Names that don’t resolve inside the namespace fall back to the global scope.
• Reopening. The same namespace name may be opened more than once, and the contents are merged.
• Forward references work across the whole file, exactly as they do at the top level.
• No nesting. A namespace cannot be declared inside another namespace.
• Native namespaces are reserved. A script cannot declare a namespace that natives were declared in, and System is always off limits. See Native functions.

14. Preprocessor

Runs on the token stream before parsing. Two directives are supported.

#include

#include "utils.mec"

• Path is resolved relative to the including file first. If it is not found there, each include search directory given to the compiler (MecCompile -I <dir>, see TOOLCHAIN.md) is tried in order. Absolute paths are used as is.
• Each file is included at most once, so diamond includes are safe.
• A circular include is a compile error, not a hang.
• A missing file is a compile error.
• Errors inside an included file are reported against that file’s own line numbers.

#define

Object-like macros only.

#define WIDTH  10
#define HEIGHT 5
#define AREA   (WIDTH * HEIGHT)

System::PrintInt(AREA);        // 50

• A name is a macro only from its #define onward.
• A macro body may reference an earlier macro, which is re-scanned and expanded.
• Self-referential and mutually-referential macros expand once and stop.
• An empty replacement is allowed and vanishes at the use site.
• Function-like macros (#define SQ(x) ((x)*(x))) are a compile error.
• There are no conditional directives (#ifdef, #if, #endif, #undef).
• A macro defined in an including file is visible inside included files.

15. Native functions

Native functions are implemented by the host application and called from a script. They are declared in a signature file that the build supplies to the compiler.

Calling convention

Every native must be called through the namespace it was declared in:

System::Yield(10);
System::PrintInt(count);

A bare Yield(10) is a compile error.

Declaration syntax

A declaration written outside any namespace goes into System:

[native 3] void PrintInt(int i);              // called as System::PrintInt(1)
[native 8] void StrCopy(byte dest[], int destCapacity, string src);

Each declaration needs a unique [native N] id that maps to the host’s implementation. A native declared here but not resolved by the host fails at runtime (vmNativeFunctionNotResolved), not at compile time.

Namespaces

Wrap declarations in a namespace block to group them under a name of your own:

namespace CAN {
    [native 301] void Send(uint id, byte *buffer, int length);
    [native 302] int Read(uint id, byte *buffer, int length);
}

CAN::Send(0x100, frame, 8);

• The namespace only changes the name a script calls the native by. There is no runtime cost and no effect on the compiled binary, and the [native N] id is still the only thing the host resolves against.
• Namespaces cannot be nested, same as in a script.
• A namespace used by any native is reserved, so a script cannot declare one with the same name. System is reserved whether or not anything is declared in it.
• Only the namespace is reserved, not the names inside it. With CAN::Read declared, a script is still free to declare its own Read variable or function, or a Data::Read of its own.

Callback parameters

A native can take a script function as an argument. The parameter type is func, and the script passes a bare function name, no parentheses:

namespace CAN {
    [native 303] void Subscribe(uint node, uint idMatch, uint idMask, func(uint id, byte data[], int length) handler);
}

void onFrame(uint id, byte data[], int length) {
    // data[0] .. data[length - 1] is the frame payload
}

CAN::Subscribe(0, 0x100, 0x7FF, onFrame);

The parameter list after func is the signature the script function must have. It always returns void. The compiler checks the function’s parameter count, each parameter’s type, and whether it is an array, and reports a mismatch at the call site. A bare func with no parameter list accepts any void function; a wrong parameter count is then only caught when the host calls it (vmCallArgCountError).

An array parameter in a callback is host-owned memory that lives only for the duration of the call. Index it or pass it on to another array parameter as usual, and copy anything you want to keep into a script array before returning.

Reference set

SetError

SetError(int) records an error code without halting the VM. The host reads it back after the run (MecVm::GetScriptError()). The last call wins. The default is 0.

if (sensorReading < 0) {
    System::SetError(42);
}

16. Runtime Model and Limits

• No heap. Globals, locals, and call frames all live in one buffer supplied by the host. The VM never allocates at runtime.
• 64 KB bytecode ceiling. A single compiled binary, including everything pulled in by #include, cannot exceed 65,535 bytes of bytecode.
• Fixed stack. The host sets the stack size. Deep recursion or large local arrays can exhaust it (vmStackOverflow).
• Bounds checking. Stack overflow/underflow and out-of-range pointer dereferences are caught and halt the VM rather than corrupting memory. The host can disable this for targets that cannot afford the checks. A local, global, or array-parameter index that runs off the end of its array is also caught (vmArrayIndexOutOfBounds); see “Bounds checking” under Arrays.
• Division by zero halts the VM (vmDivisionByZero) for integer and float operands.
• No overflow detection. Arithmetic wraps silently.
• No exceptions. There is no try/catch/throw. A genuine runtime error halts the VM. Use SetError for recoverable conditions.
• No string escape sequences.

VM status

A run ends with a status code. vmEnd is normal completion. Others include vmDivisionByZero, vmStackOverflow, vmStackUnderflow, vmPointerOutOfBounds, vmArrayIndexOutOfBounds, vmNativeFunctionNotResolved, and vmUnknownInstruction.

17. Complete Example

#define TABLE_SIZE 8

int primes[TABLE_SIZE];
int primeCount = 0;

bool isPrime(int n) {
    if (n < 2) {
        return false;
    }
    for (int d = 2; d * d <= n; d++) {
        if (n % d == 0) {
            return false;
        }
    }
    return true;
}

void collectPrimes() {
    int candidate = 2;
    while (primeCount < TABLE_SIZE) {
        if (isPrime(candidate)) {
            primes[primeCount] = candidate;
            primeCount++;
        }
        candidate++;
    }
}

class Accumulator {
    int total;

    void add(int v) {
        this.total += v;
    }

    int get() {
        return this.total;
    }
}

collectPrimes();

Accumulator acc;
for (int i = 0; i < primeCount; i++) {
    System::PrintInt(primes[i]);
    acc.add(primes[i]);
}

System::PrintLine("sum:");
System::PrintInt(acc.get());

Output:

2
3
5
7
11
13
17
19
sum:
77

TCM System Functions

This is a reference for every native function callable from a MecScript script running on the TCM including:

• General-purpose functions under System:: for debugging and time management.
• TCM-specific functions under Runtime::, Device::, CAN:: and Output:: for reading live device state, talking to the CAN bus and driving script-controlled outputs.

Quick Reference

Strings & Debugging (System::)

Time

Script Yielding

Runtime Channels (Runtime::)

CAN Bus (CAN::)

Output Control (Output::)

Device Information (Device::)

Calling Convention

Every native function is called through its namespace.

float rpm = Runtime::ReadReal(RT_ENGSPD);
CAN::Poll();
System::Yield(10);

Calling a native bare (Yield(10);, Poll();) or through the wrong namespace (System::Runtime::Read(1);) fails to compile. Function names are case-sensitive and must match the names in this manual exactly.

A callback handler passed to CAN::Subscribe (a func-typed parameter) is the one exception: it’s a bare script function name, not called through any namespace - see CAN Receive Callbacks.

Runtime ids (the uint id arguments to the Runtime:: functions) are plain numbers assigned by the device’s .mdef. Rather than hard-coding them, #include "mtc.mec" and use the RT_ names it defines - see Include Files.

Every CAN:: function takes a node as its first argument, numbered from zero: 0 is the bus MectriCal labels CAN 1 and 1 is CAN 2. CAN::Subscribe and CAN::Unsubscribe also accept 2 for both buses; everywhere else 2 is rejected. The include file provides CAN1, CAN2 and CAN_BOTH for these.

Included Device Definition Files

Device header file(s) ship along side the compiler, so a script can refer to channels, buses, bitrates, etc by name instead of by number. Include it at the top of the script:

#include "tm16.mec"

The file name is the device’s name in lower case: mtc.mec for the MTC, tm16.mec for the TM16. The compiler already knows where the shipped headers live, so the plain file name works wherever the script itself is saved. Including the same file more than once (e.g. from two of your own include files) is harmless.

A runtime channel’s name is RT_ followed by its abbreviation in upper case (the “Engine Speed” channel becomes RT_ENGSPD). Each define carries the channel’s full label as a trailing comment, so the quickest way to find a channel is to open the header and search for the channel name.

You are free to define your own constants too.

#include "tm16.mec"

#define MY_SOLENOID 4

float rpm = Runtime::ReadReal(RT_ENGSPD);
CAN::SetupNode(CAN2, true, CAN_BITRATE_500K, true, false);
Output::SetActiveLevel(MY_SOLENOID, LOW);

The header only provides names - it doesn’t change what any function does. A channel that isn’t writeable still refuses Runtime::Write whether it’s addressed by RT_ name or by number.

String/Debug Output

Print, PrintLine, PrintInt, PrintFloat, PrintFormat and PrintBuffer all write to the same destination: a debug message sent to a connected PC over the device’s Ethernet port, rate-limited so a busy loop can’t flood it. None of them do anything unless all of the following are true:

• MectriCal is connected to the device and has debug output active, AND
• The specific script has its “Debug” option enabled in its configuration.

[IMPORTANT] Always disable debug when it’s no longer required.

System::Print("state=");
System::PrintInt(state);
System::PrintLine(" (idle)");
System::PrintFormat("battery: %f V\n", batteryVolts);

str in Print/PrintLine/PrintFormat must be a string - a compile-time string constant, not a byte[] buffer. Use PrintBuffer for buffer content instead (see String Buffers).

System::Print

void System::Print(string str)

Prints a string literal with no newline.

System::Print("hello");

System::PrintLine

void System::PrintLine(string str)

Prints a string literal followed by a newline. Use it for the last piece of a line built up from several Print/PrintInt calls. An empty string "" is not accepted as an argument, so end the line with real text, or use PrintFormat with a \n in its format string.

System::PrintLine("hello");

System::PrintInt

void System::PrintInt(int i)

Prints i as a single integer value.

int i = 100;
System::PrintInt(i); // 100

System::PrintFloat

void System::PrintFloat(float f) 

Prints f as a decimal float (%f format).

int f = 123.4;
System::PrintFloat(f); // 123.4

System::PrintFormat

void System::PrintFormat(string str, float f) // 

Prints str as a printf-style format string with f as its one and only argument.so only a single %f-style specifier makes sense. Anything else in the string that consumes an argument is undefined, the same way a mismatched printf format is in C.

System::PrintFormat("The value is %f", 123.4); // The value is 123.4

System::PrintBuffer

void System::PrintBuffer(byte buf[], int capacity)

Prints buf’s contents up to its null terminator, or up to capacity bytes, whichever comes first. See StringBuffers.

String Buffers

string constants are immutable and can’t be built or modified at runtime - for text a script assembles itself (formatting a value, building a label from CAN data, etc.) it needs a byte[] buffer instead, plus the five string natives that operate on it. All five are C snprintf-style: every one takes an explicit capacity and truncates rather than overflowing.

byte msg[32];
System::StrCopy(msg, 32, "state=");

byte num[16];
System::IntToStr(num, 16, 42);

// StrAppend's source is a string constant only - buffer-to-buffer append isn't supported
System::StrAppend(msg, 32, "42");

System::PrintBuffer(msg, 32);   // msg is byte[] - use PrintBuffer, not Print/PrintLine

Two easy mistakes to make:

• StrCopy/StrAppend’s source (src) is always a string constant, never another byte[] buffer. There’s no buffer-to-buffer append.
• A byte[] buffer can never be passed where a string parameter is expected. A freshly declared buffer is zero-filled, so StrLength on one that’s never been written returns 0.

System::StrLength

int System::StrLength(byte buf[], int capacity)

Scans up to capacity bytes for a \0 and returns how many bytes precede it: 0 if buf starts with \0, capacity if no terminator is found.

System::StrCopy

void System::StrCopy(byte dest[], int destCapacity, string src)

Copies src into dest, truncating and null-terminating to fit within destCapacity.

System::StrAppend

void System::StrAppend(byte dest[], int destCapacity, string src)

Appends src onto dest’s existing null-terminated content, truncating and null-terminating to fit within destCapacity.

System::IntToStr

void System::IntToStr(byte dest[], int destCapacity, int value)

Formats value as decimal text into dest, truncating and null-terminating to fit within destCapacity.

System::StrEquals

bool System::StrEquals(byte a[], int capacityA, byte b[], int capacityB)

Returns true if a and b’s null-terminated contents are identical, each scanned up to its own capacity.

Timing

uint nowMs = System::NowMs();
uint nowUs = System::NowUs();

NowMs/NowUs read the device’s uptime from the same free-running hardware timer, but with different wrap periods.

System::NowMs

uint System::NowMs()

Uptime in milliseconds. Wraps every ~49.7 days (2^32 milliseconds), which makes it the safer default for a script tracking longer-running state (e.g. time since ignition-on).

System::NowUs

uint NowUs()

Uptime in microseconds. Wraps every ~71.58 minutes (2^32 microseconds). Because the two clocks wrap at different points, NowMs() and NowUs() / 1000 only agree with each other for the first ~71.58 minutes after boot - once NowUs has wrapped, NowMs keeps counting while NowUs has reset near zero, so don’t rely on them staying numerically related.

System::Yield

void System::Yield(uint t)

Pauses the calling script for t milliseconds, letting other threads (and the rest of the script scheduler) run. This is the standard way to pace a script’s own loop instead of spinning:

while (1) {
    // ... do work ...
    System::Yield(20);   // ~50 Hz loop
}

System::YieldUntil

uint System::YieldUntil(uint lastTime, uint delay)

A fixed-period yield: sleeps until lastTime + delay, then returns the new lastTime (lastTime + delay) for the caller to feed back in on the next iteration. Unlike Yield, which always sleeps for a fixed duration from now, this keeps a loop’s period accurate even if the loop body’s own work takes a variable amount of time each iteration:

uint lastWake = System::NowMs();
for (;;) {
    // ... do work ...
    lastWake = System::YieldUntil(lastWake, 20);   // 20 ms period, not 20 ms + work time
}

The function takes and returns lastTime explicitly rather than updating it in place (MecScript has no reference parameters) - always reassign the return value back onto the variable you pass in, or the period will drift.

Runtime Channels

Runtime channels are the live values used throughout the TCM (engine RPM, gear, clutch pressures, launch targets and so on). Each is identified by its Runtime ID, available by name as RT_... from the device’s include file.

Channels come in two flavours from a script’s point of view:

• Read/Write work in the channel’s integer representation: the real value with its decimal point removed, so a channel displayed as 123.4 (one decimal place) reads as 1234, and writing 1234 sets it to 123.4. A channel with no decimal places reads and writes as-is.
• ReadReal/WriteReal work in floating point units (123.4) and are the simpler choice unless you specifically want integer maths. The TCM is equipped with an FPU so floating point operations are trivial.

Reads of an ID that doesn’t resolve to anything return 0. Writes only succeed (return true) if the target channel is writeable. Lots of channels are computed outputs, not inputs, and will refuse the write.

#include "tm16.mec"

void main() {
    // Engine Speed has 1DP precision
    int rpmInt = Runtime::Read(RT_ENGSPD) / 10; // 6500.0 rpm reads as 65000
    float rpm  = Runtime::ReadReal(RT_ENGSPD);  // 6500.0

    Runtime::Write(RT_USERCH1, rpmInt + 100);
    Runtime::WriteReal(RT_USERCH2, rpm + 100.0);
}

main();

Runtime::Read

int Runtime::Read(uint id)

Reads the channel as an integer with the decimal point removed. Returns 0 if id is unknown.

int anv1 = Runtime::Read(RT_ANV1); // 3DP: 1.234V = 1234

Runtime::ReadReal

float Runtime::ReadReal(uint id)

Reads the channel as a float in its real units. Returns 0 if id is unknown.

float anv1 = Runtime::ReadReal(RT_ANV1); // 3DP: 1.234V = 1.234

Runtime::Write

bool Runtime::Write(uint id, int value)

Writes value, an integer with the decimal point removed, to the channel. Returns true if the channel accepted the write, false if id is unknown or the channel is not writeable.

// Vehicle speed is 1DP so 1234 = 123.4 km/h
if (!Runtime::Write(RT_VEHICLESPEED, 1234)) {
    System::Print("Vehicle Speed not assigned to Script");
}

Runtime::WriteReal

bool Runtime::WriteReal(uint id, float value)

Writes value, a float in the channel’s real units. Returns true if the channel accepted the write, false if id is unknown or the channel is not writeable.

if (!Runtime::WriteReal(RT_VEHICLESPEED, 123.4)) {
    System::Print("Vehicle Speed not assigned to Script");
}

CAN Bus

Every CAN:: function takes a node as its first argument (0 indexed):

• 0 = CAN 1,
• 1 = CAN 2
• Subscribe/Unsubscribe also accept 2 = both buses.

Node Setup

CAN::SetupNode

bool CAN::SetupNode(uint node, bool enable, uint bitrateSelect, bool termination, bool listenOnly)

Configures and restarts a CAN node from the script, replacing the node’s settings from the calibration. Returns true on success, false if node is not 0 or 1.

• enable - false turns the node off entirely (no transmit, no receive, termination off). The other arguments are still stored but have no effect until the node is enabled again.
• bitrateSelect
  • 0 = Custom bit timing
  • 1 = 125 kbit/s
  • 2 = 250 kbit/s
  • 3 = 500 kbit/s
  • 4 = 1 Mbit/s
  • *Any other value leaves the bit timing as it was.
• termination - switches the node’s on-board 120R termination resistor on or off.
• listenOnly - true puts the node in silent mode: it receives frames but never transmits or acknowledges, and the node’s configured CAN transmit channels are stopped. Use it to read from a bus the TCM must not disturb.

// CAN 2: enabled, 500 kbit/s, termination on, normal (not listen-only) mode
bool canOk = CAN::SetupNode(CAN2, true, CAN_BITRATE_500K, true, false);

Calling it restarts the node, so any frames in flight on that bus are lost. Call it once at script start, NOT from inside the loop. The new settings are not saved to flash by the call itself, so a script that depends on them should apply them every time it starts.

Raw CAN I/O (polling)

Send/Read are the simple, polling pair. Both target one bus, so node must be 0 or 1. 2 is rejected (Send does nothing, Read returns -1).

#include "mtc.mec"

byte txBuf[8];
byte rxBuf[8];

void doCan() {
    txBuf[0] = 1;
    CAN::Send(CAN1, 0x100, txBuf, 8);

    int n = CAN::Read(CAN2, 0x200, rxBuf, 8);
    if (n > 0) {
        System::PrintInt(rxBuf[0]);
    }
}

doCan();

CAN::Send

void CAN::Send(uint node, uint id, byte buffer[], int length)

Queues a CAN message with identifier id and the first length bytes of buffer (at most 8) for transmission on node. The call returns as soon as the frame is queued; it does nothing if node is not 0 or 1 or length is 0.

byte txBuf[8] = { 0, 1, 2, 3, 4, 5, 6, 7 };
CAN::Send(CAN1, 0x100, txBuf, 8);

CAN::Read

int CAN::Read(uint node, uint id, byte buffer[], int length)

Copies the most recently received frame with identifier id on node into buffer, up to length bytes, and returns the number of bytes copied. Returns -1 if no frame with that id has been seen on that bus yet.

byte rxBuf[8];
int read = CAN::Read(CAN2, 0x200, rxBuf, 8);
if (read > 2) {
    int engineSpeed = (rxBuff[1] << 8) | rxBuff[0]; // 0DP
    Runtime::Write(RT_ENGSPD, engineSpeed * 10); // 1DP
}

The device keeps the latest frame for each node/id pair a script has asked about, and each Read call copies out of that store, so reading a frame doesn’t consume it: the same frame is returned again until a newer one arrives. The system holds a fixed number of node/id pairs (16, shared across all running scripts); once it’s full, Read on a pair it isn’t already tracking returns -1. This is fine for a handful of ids a script cares about. If you need every frame on a range of ids, or lower latency, use the callback API below instead.

CAN Receive Callbacks

CAN::Subscribe registers a script function to be called for every received frame whose id matches an id/mask pair, on CAN 1, CAN 2 or both. One subscription can cover many ids (see Id/Mask Matching). Handlers don’t run the instant a frame arrives: matching frames are queued for the script, and CAN::Poll() - called from the script’s own loop - runs each handler in turn on the script’s own thread. This means a callback can never delay real CAN traffic, but also means it only ever fires when the script calls CAN::Poll().

void onEngineData(uint id, byte data[], int length) {
    if (length >= 2) {
        Runtime::Write(RT_TPS, (data[0] << 8) | data[1]);
    }
}

CAN::Subscribe(CAN1, 0x0CF00400, 0x1FFFFF00, onEngineData);

while (true) {
    CAN::Poll();
    System::Yield(10);
}

CAN::Subscribe

void CAN::Subscribe(uint node, uint idMatch, uint idMask, func(uint id, byte data[], int length) handler)

Subscribes a handler to a range of CAN messages:

• node - 0 = CAN 1, 1 = CAN 2, 2 = both (CAN1, CAN2, CAN_BOTH from the include file).
• idMatch/idMask - a frame matches when (frame.id & idMask) == (idMatch & idMask). A mask of 0 matches every id on the node.
• handler - a bare script function name (no parentheses, no namespace), which must be declared with exactly this signature:

void handler(uint id, byte data[], int length) { ... }

id is the received frame’s identifier, data holds its payload and length is how many of those bytes are valid (0-8). A handler with the wrong parameter count or types is rejected at compile time.

data is only valid until the handler returns. Index it, or pass it straight on to another function that takes a byte array (such as CAN::Send), but copy it into a script-declared array if you need the bytes afterwards. Each frame delivered to a handler also uses a little extra script stack on top of the handler’s own locals, so a script running very close to its stack limit can halt with a stack-overflow fault on delivery rather than silently missing the callback.

Calling Subscribe again with the same node/idMatch/idMask replaces the existing subscription’s handler rather than adding a second one.

CAN::Unsubscribe

void CAN::Unsubscribe(uint node, uint idMatch, uint idMask)

Removes a subscription. Pass the exact same three values it was registered with.

CAN::Poll

int CAN::Poll()

Runs the handlers for every matching frame received since the last call, oldest first, and returns how many handlers were fired. A subscribing script must call it once per loop iteration, before yielding, or queued frames simply sit until the next call.

The queue holds a fixed number of frames per script. If a script falls behind a busy bus (e.g. it’s blocked doing other work), the oldest undelivered frames are dropped rather than the queue growing. Keep the loop tight and call Poll() regularly if you’re subscribing to high frequency message(s) or a wide mask. Calling Poll() from inside a handler (directly or indirectly) does nothing and returns 0.

Id/Mask Matching

The match is a bitwise AND against both sides, not a range check:

(frame.id & idMask) == (idMatch & idMask)

• Bits set in idMask are the ones that must match.
• Bits clear in idMask are don’t-care and match any value.

A few common patterns:

CAN::Subscribe(CAN1, 0x100, 0xFFFFFFFF, handler1);   // exact id 0x100 only
CAN::Subscribe(CAN1, 0x100, 0x700,      handler2);   // every id from 0x100-0x1FF
CAN::Subscribe(CAN1, 0,     0,          handler3);   // every id on CAN 1 (not recommended)

The frame’s actual ID is always passed to the handler as its first argument, so a single wide-mask subscription can still tell which specific id triggered each call:

void handler2(uint id, byte data[], int length) {
    if (id == 0x101) { ... }
    else if (id == 0x150) { ... }
}

Output Control

Script outputs are a dedicated pool of up to 24 output channels that can be used to drive solenoids etc.
outputId ranges from 1-24, not 0-based. ID 0 or anything above 24 resolves to nothing and does nothing.
Each output has to be assigned to a physical pin in the device’s configuration before a script can usefully drive it. An unassigned output accepts every call here without error but has no effect on hardware.

#include "tm16.mec"

#define CENTRE_DIFF_SOLENOID 6

void SetupSolenoids() {
    Output::SetActiveLevel(CENTRE_DIFF_SOLENOID, LOW);        // Active low
    Output::SetFreq(CENTRE_DIFF_SOLENOID, 2000.0);            // 2000 Hz
}

SetupSolenoids();

float TorqueSplitCurrent() { ... }

// Main Script Loop
while(1) {
    float diffMa = TorqueSplitCurrent();
    Output::SetCurrent(CENTRE_DIFF_SOLENOID, diffMa); // Closed-loop current control, mA
    System::Yield(5); // 200 Hz loop
}

Output::SetActiveLevel

void Output::SetActiveLevel(byte outputId, int level)

Sets whether the output is driven active-high (1) or active-low (0). LOW and HIGH definitions are in the device include file.

Output::SetActiveLevel(MY_SOLENOID, LOW);

Output::SetEffectiveResistance

void Output::SetEffectiveResistance(byte outputId, float ohms)

Auxiliary Outputs Only
Tells the current control system the resistance of the connected load. Used to help translate the current target into a drive duty. Only relevant in current-control mode when the output is assigned to an auxiliary output rather than a solenoid output.

void Output::SetEffectiveResistance(MY_SOLENOID, 9.5);

Output::SetFreq

void Output::SetFreq(byte outputId, float frequency)

Sets the output’s switching frequency in Hz:

• PWM rate in PWM (duty) mode.
• Base frequency in current-control mode.

PWM Range: 0.5 - 20000 Hz
Current Control Range: See below

Output::SetFreq(MY_SOLENOID, 1000.0); // 1000 Hz

Current Control Frequency

When an output is in current control mode, it’s frequency must be one of the following options:

• 110 Hz
• 200 Hz
• 300 Hz
• 400 Hz
• 500 Hz
• 600 Hz
• 700 Hz
• 800 Hz
• 900 Hz
• 1000 Hz
• 2000 Hz
• 3000 Hz
• 4000 Hz

PWM Mode Frequency

In PWM mode, any frequency up to 20000 Hz (20 KHz) is fine.
Once the duty cycle has been set, putting the output into fixed PWM mode, the frequency can be changed at will, even without updating the duty cycle again. This makes it possible to do variable frequency outputs such as a tacho output.

Output::SetDuty

void Output::SetDuty(byte outputId, float dutyCycle)

Puts the output in fixed-duty PWM mode at dutyCycle percent (0-100) and clears any current target.

Output::SetDuty(MY_SOLENOID, 12.3); // 12.3%

Output::SetCurrent

void Output::SetCurrent(byte outputId, float milliAmps)

Puts the output in closed-loop current-control mode with a target of milliAmps and clears any duty setpoint.

Output::SetCurrent(MY_SOLENOID, 900.0); // 900mA or 0.9A

Output Current Range

• Solenoid Outputs in single channel mode can command up to 1.5A.
• Solenoid Outputs in paired channel mode can command up to 2.7A.
• Auxiliary Outputs can command up to 5A. (high side or low side).

Device Identity

uint serial = Device::ReadSerialNumber();
uint key1   = Device::ReadVendorKey(1);
uint key2   = Device::ReadVendorKey(2);   // any keyId other than 1 or 2 returns 0

A common use is locking a script to a specific device or vendor: compare the serial number and/or a vendor key that only the vendor knows and gives to the user, against an expected value at script start and refuse to run if it doesn’t match.

bool AuthorizeScript(uint serial, uint key) {
    // Some kind of non trivial cypher...
    const uint expected = ((serial & 0xAA55AA55) << 16) + (serial ^ 0xDEADBEEF);
    return key == expected;
}

const uint serial = Device::ReadSerialNumber();
const uint key1   = Device::ReadVendorKey(1);

if (!AuthorizeScript(serial, key1)) {
    // Invalid key
    System::Print("Key Invalid. Script will not run.");
    return; // Returning from the scripts top level will terminate execution.
}

Device::ReadSerialNumber

uint Device::ReadSerialNumber()

Returns the device’s serial number.

Device::ReadVendorKey

uint Device::ReadVendorKey(int keyId)

Returns one of two general-purpose 32-bit calibration values (“Script Vendor Hardware Key 1/2”), set like any other calibration value in MectriCal. keyId is 1 or 2; any other value returns 0.