Skip to content

Latest commit

 

History

History
251 lines (178 loc) · 9.39 KB

input.pointer.md

File metadata and controls

251 lines (178 loc) · 9.39 KB
Raw

input.pointer (DRAFT)

API for pointing device drivers:

  • mouse
  • trackball
  • trackpad

Object filename description:

input.pointer.model.spin

Nomenclature:

  • X-axis: horizontal, or left/right axis
  • Y-axis: vertical, or up/down axis
  • Absolute position: position expressed as a specific coordinate or location within a grid.
  • Relative position (delta): position expressed as the difference from the previous position.

Base Methods

These are methods that are common to all IMU drivers

Method Description Param Returns
start() Start driver using default settings n/a cog id+1
startx() Start driver using explicitly defined settings Notes 2-4 cog id+1
stop() Stop the driver n/a n/a
defaults() Set device factory default settings n/a n/a

Notes:

  1. When starting the driver with start(), the driver can be configured using constant overrides in the parent object.

  2. For SPI-connected devices:

    • startx(CS_PIN, SCK_PIN, MOSI_PIN, MISO_PIN): status
    • For some devices, a MODEL_SPI_BC variant exists, which directs the driver to use a bytecode-based engine that while much slower, doesn't use another cog. Replace MODEL with the device model #.
    • For SPI-connected devices: 4-wire SPI is used by default. If supported by the device, 3-wire SPI can be chosen by setting MOSI_PIN and MISO_PIN to the same I/O pin. The startx() method will check for this and set the device's 3-wire SPI mode register.

  3. For I2C-connected devices:

    • startx(SCL_PIN, SDA_PIN, I2C_FREQ, ADDR_BITS): status
    • If no particular interface preprocessor symbol is defined when building, the driver will default to the PASM-based I2C engine.
    • For some devices, a MODEL_I2C_BC variant exists, which directs the driver to use a bytecode-based engine that while much slower, doesn't use another cog, and is slightly smaller.
    • Not all devices support alternate I2C addresses.

  4. For all variants: There may be a RST_PIN parameter, for specifying an optional reset pin (device-dependent). The pin is only validated in the reset() method, and is ignored if set outside the allowable range.

  5. startx() returns the launched cog number+1 of com engine used on success.

  6. startx() returns FALSE (0) if the driver fails to start, for these possible reasons:

    • No more cogs available
    • One or more specified I/O pins are outside allowed range
    • If supported by the device, dev_id() didn't return the expected value

  7. defaults() may simply call reset(), if sensible, as opposed to calling several other driver methods, in order to reduce memory usage.

  8. Most (but not all) drivers also provide the following methods:

Method Description Param Returns
dev_id() Read model-unique identification register n/a model/dev ID
reset() Perform a hard or soft-reset of the device n/a n/a

  1. Drivers may have one or more preset_() methods, that establish a set of pre-set settings.

  2. stop() performs the following tasks:

    • Stop any extra cogs that were started (if applicable)
    • Clear all global variable space used to 0

Pointing devices

Method Description
abs_x() Pointer absolute position, X-axis
abs_y() Pointer absolute position, Y-axis
set_abs_x() Manually set pointer absolute position, X-axis
set_abs_y() Manually set pointer absolute position, Y-axis
set_abs_x_max() Set pointer absolute position X-axis maximum
set_abs_y_max() Set pointer absolute position Y-axis maximum
set_abs_x_min() Set pointer absolute position X-axis minimum
set_abs_y_min() Set pointer absolute position Y-axis minimum
set_sensitivity_x() Set pointer sensitivity, X-axis
set_sensitivity_y() Set pointer sensitivity, Y-axis
pointer_rel_x() Pointer relative position (delta), X-axis
pointer_rel_y() Pointer relative position (delta), Y-axis

abs_x()

Pointer absolute position, X-axis

  • Parameters: none
  • Returns: absolute position coordinate
  • NOTE: coordinate return is confined to the X-axis limits set by set_abs_x_min() and set_abs_x_max()

abs_y()

Pointer absolute position, Y-axis

  • Parameters: none
  • Returns: absolute position coordinate
  • NOTE: coordinate return is confined to the Y-axis limits set by set_abs_y() and set_abs_y()

set_abs_x()

Manually set pointer absolute position, X-axis

  • Parameters:
    • x: X-axis position
  • Returns: none
  • NOTE: this could be used e.g., to set the initial value returned by abs_x()

set_abs_y()

Manually set pointer absolute position, Y-axis

  • Parameters:
    • y: Y-axis position
  • Returns: none
  • NOTE: this could be used e.g., to set the initial value returned by abs_y()

set_abs_x_max()

Set pointer absolute position X-axis maximum

  • Parameters:
    • x: X-axis maximum value
  • Returns: none
  • NOTE: this could be used e.g., to constrain the position reported to the dimensions of a screen

set_abs_y_max()

Set pointer absolute position Y-axis maximum

  • Parameters:
    • y: Y-axis maximum value
  • Returns: none
  • NOTE: this could be used e.g., to constrain the position reported to the dimensions of a screen

set_abs_x_min()

Set pointer absolute position X-axis minimum

  • Parameters:
    • x: X-axis minimum value
  • Returns: none
  • NOTE: this could be used e.g., to constrain the position reported to the dimensions of a screen

set_abs_y_min()

Set pointer absolute position Y-axis minimum

  • Parameters:
    • y: Y-axis minimum value
  • Returns: none
  • NOTE: this could be used e.g., to constrain the position reported to the dimensions of a screen

set_sensitivity_x()

Set pointer sensitivity, X-axis

  • Parameters:
    • x: X-axis movement sensitivity
  • Returns: none
  • NOTE: this affects the step size of delta position reports read by pointer_rel_x() which in turn supplies data returned by abs_x()

set_sensitivity_y()

Set pointer sensitivity, Y-axis

  • Parameters:
    • y: Y-axis movement sensitivity
  • Returns: none
  • NOTE: this affects the step size of delta position reports read by pointer_rel_y() which in turn supplies data returned by abs_y()

pointer_rel_x()

Pointer relative position (delta), X-axis

  • Parameters: none
  • Returns: position delta/relative position
  • Aliases: read_x()
  • NOTE: this is usually the function that returns data directly from the device, so in order to read any position data, it must be called first. The data returned may be ignored, if only absolute position is desired.

pointer_rel_x()

Pointer relative position (delta), X-axis

  • Parameters: none
  • Returns: position delta/relative position
  • Aliases: read_y()
  • NOTE: this is usually the function that returns data directly from the device, so in order to read any position data, it must be called first. The data returned may be ignored, if only absolute position is desired.

Availability of other methods vary by specific device type and model.

Built-in symbols

TBD

Note: 'x' indicates device driver-specific values

Global variables

VAR

    { absolute position (signed 32-bit) }
    long _pointer_x, _pointer_y

    { absolute position constraints (signed 32-bit) }
    long _pointer_x_max, _pointer_y_max, _pointer_x_min, _pointer_y_min

    { pointer sensitivity (signed 32-bit) }
    long _pointer_x_sens, _pointer_y_sens

File Structure

input.pointer.model.spin - driver object
|-- #include "input.pointer.common.spinh" - provides standard API and code shared by all pointer drivers
|-- OBJ core: "core.con.model.spin" - HW-specific constants
|-- OBJ com: "com.xxx.spin" - Low-level communications engine (I2C, SPI, OneWire, etc)
|-- OBJ time: "time.spin" - time-delay methods

Build examples

1. Build the Grove mini-trackball serial demo for P1, using FlexSpin's PASM backend, and the PASM-based I2C engine:

flexspin -L$HOME/spin-standard-library/library Grove-mini-trackball-demo-serial.spin

2. The same, but build using FlexSpin's bytecode backend:

flexspin --interp=rom -L$HOME/spin-standard-library/library Grove-mini-trackball-demo-serial.spin

3. The same as #2, but using the bytecode-based I2C engine:

flexspin --interp=rom -L$HOME/spin-standard-library/library -DGROVE_MINI_TRACKBALL_I2C_BC Grove-mini-trackball-demo-serial.spin