git.haldean.org wallbot / master lang / ideas.txt
master

Tree @master (Download .tar.gz)

ideas.txt @masterraw · history · blame

Primitives:
- boolean
- int
    signed 28-bit integer
- Q vectors
    dimension k (fixed at compile time), represents robot state
- R vectors
    dimension n (fixed at compile time), represents robot position
- register
    static storage whose value influences the behavior of the whole system
- channel
    hardware output channel with a buffer, takes signals as input
- channelset
    a set of channels that can be started and joined together

Registers:
    %pivl: rvec
        position of left pivot in real space
    %pivr: rvec
        position of right pivot in real space
    %radl: int
        difference between left radius at robot-zero and current radius
    %radr: int
        difference between right radius at robot-zero and current radius
    %step: int
        amount of chain let out in a single step
    %cal: bool
        true if the robot is calibrated (i.e., if pivl, pivr, radl and radr are
        properly initialized)
    %pen: bool
        true if the pen is engaged, false otherwise
    %mle: channel
        motor left enable channel
    %mld: channel
        motor left direction channel
    %mls: channel
        motor left step channel
    %mre: channel
        motor right enable channel
    %mrd: channel
        motor right direction channel
    %mrs: channel
        motor right step channel

WiFi and serial communication are done via "remote registers", which are normal
registers that the interpreter keeps updated when remote requests come in, or
that cause a request to go out over serial or WiFi when written to. Remote
registers include:

    %jogq: qvec
        user jog requests of the Q position, in microns per second
    %jogr: rvec
        user jog requests of the R position, in microns per second
    %go: bool
        whether the go button is depressed

Built-in words:

    true, false

    swap (a b -- b a)
    drop (a -- )
    dup (a -- a a)

    assert (a -- )
        if a is not true, halts the interpreter

    add, sub, div, mul, mod (v0 v1 -- res)
        arithmetic on integers and vectors, all vector arithmetic is
        element-wise
    neg (v -- res)
        negate a number or vector

    qv (qn, ..., q1, q0 -- q)
        makes a Q vector
    rv (rn, ..., r1, r0 -- r)
        makes an R vector
    get (vec i -- vec[i])
        gets an element from a qvec or rvec
    dot (v0 v1 -- res)
        dot product of two vectors

    load (register -- value)
        register load
    store (value register -- )
        register store

    push (sig chan -- )
        push a signal into a channel
    wait (chan -- )
        tell the channel to buffer requests until the next flush
    flush (chan -- )
        execute all requests on the channel

    attach (channelset channel -- channelset)
        add a channel to a set
    begin (channelset -- channelset)
        puts all associated channels into the wait state
    commit (channelset -- channelset)
        flushes all channels simultaneously, blocks until all signals are sent

Control flow:

    { ( -- )
        opens a block; instructions inside the block are not executed
    } ( -- block )
        closes a block, creating a block that can be passed to something else
    if ( block bool -- )
        if bool is true, runs block. otherwise, just pops both off the stack
        and does nothing
    loop ( block bool -- )
        if bool is true, runs the block. repeats running block until bool is no
        longer true

A do-while loop that calls 'func' on the top value 10 times then looks like:

    10
    {
        swap         # ( x i -- i x )
        func swap    # ( i x -- f(x) i )
        1 - dup 0 neq # ( f(x) i -- f(x) i-- (i-- == 0) )
    }
    true loop

All measurements done in whole microns to avoid floating point

Signals:

    Signals are a triple of high-period, low-period (in milliseconds) and pulse
    count, and are the input into channels. There are a few special-cases:
    
    high-period     low-period      pulses     meaning
    > 0             > 0             > 0        regular signal
    > 0             = 0             = 0        high forever
    = 0             > 0             = 0        low forever
    = 0             = 0             = 0        state unchanged
    
    Any of the three values being negative is an invalid request, and the
    interpreter should halt.
    
    3v3__      _________________________                    ______
              |                         |                  |
              |                         |                  |
              |                         |                  |
              |                         |                  |
      0__  ___/                         \__________________/
       
              |<      high period      >|<   low period   >|
              |<                 one pulse                >|