├── README.md └── axes.png /README.md: -------------------------------------------------------------------------------- 1 | # tcode-spec 2 | 3 | 4 | 5 | ## version `0.3` as of 10th May 2021 6 | 7 | T-code is a protocol for implementing UART serial communications to an adult toy. It is partly influenced by G-code, which is an alphanumeric format used to drive CNC machines, including 3D-printers. 8 | 9 | The toy or “device” will be capable of one or more functions, which are described as Linear motion, Vibration or Rotation “channels”, which can be addressed independently. 10 | 11 | Commands are sent to the device in the form of alphanumeric ASCII phrases, which are interpreted by the device, stored in a buffer and executed on the receipt of new line or `/n` character. 12 | 13 | ## Axes Conventions 14 | 15 | The range of each axis is `[0, 1)`. 16 | 17 | - the minimum position for each axis is `0` 18 | - the maximum position is `0.9999...` 19 | 20 | The default configuration for a Multi Axis Stroker Robot (or "MAxSR") is as follows: 21 | 22 | - Linear motions in three axes: 23 | 24 | - `L0` is positive up relative to the user 25 | - `L1` is positive moving away from the user 26 | - `L2` is positive moving to the user's left 27 | 28 | - Rotation in three axes: 29 | - `R0`, `R1`, `R2` are positive according to the right-hand rule around `L0`, `L1`, `L2` respectively 30 | 31 | Visually: 32 | 33 | ![Axis Diagram][axis diagram] 34 | 35 | ## Basic Command Syntax 36 | 37 | Basic commands for **L**inear move, **R**otate, and **V**ibrate take the form of a letter (`L`, `R`, or `V`) followed by a set of digits. Lower case letters (`l`, `r`, `v`) are also valid. 38 | 39 | ### Example Basic Commands 40 | 41 | | Command | Axis | Channel ID | Magnitude | 42 | | --------- | -------- | :--------: | --------- | 43 | | `L277` | Linear | `2` | `0.77` | 44 | | `R09` | Rotation | `0` | `0.90` | 45 | | `V317439` | Vibrate | `3` | `0.17439` | 46 | 47 | ### Anatomy of a basic command: `X&$$` 48 | 49 | The first digit `&` represents the channel ID (e.g. `0`-`9`). 50 | 51 | Any subsequent digits (in this case `$$`) are the magnitude. 52 | 53 | The magnitude for any channel is always a number greater than or equal to `0.0` and strictly less than `1.0`. The magnitude digits are therefore effectively the digits following a `0.____`. 54 | 55 | The magnitude corresponds to a linear position/speed, rotation position/speed, or vibration level. In situations where position or speed is possible in a forward or reverse direction 0.5 is assumed to be central or at rest. 56 | 57 | ## Advanced Commands 58 | 59 | Magnitude commands of the format `X&$$` can be augmented with additional terms to change the ramp time or speed. 60 | 61 | | Command | Axis | Channel | Effect | 62 | | ----------- | ------- | :-----: | --------------------------------------- | 63 | | `V199I2000` | Vibrate | `1` | Ramp to `0.99` over `2000` milliseconds | 64 | | `L020S10` | Linear | `0` | Ramp to `0.2` at a rate of `0.1`/sec | 65 | 66 | ### Magnitude + Time Interval 67 | 68 | Magnitude commands can be augmented with a speed term. This commands the toy to ramp to the specified magnitude over an interval of time, given in milliseconds. 69 | 70 | eg: `L&$$I£££` 71 | 72 | Where `I` (or `i`) allows the effect to be ramped in over an interval of `£££` milliseconds, starting from the current value. 73 | 74 | With this command the channel ramps to the specified level and continues at that level until given further instructions. 75 | 76 | ### Magnitude + Speed 77 | 78 | As an alternative, the rate at which the effect is ramped in can be specified. 79 | 80 | `R&$$S£££` 81 | 82 | Using `S` (or `s`) allows the effect to be ramped at a speed of `£££` per hundred milliseconds. 83 | 84 | As with time interval, the channel ramps to the specified level and continues at that level until given further instructions. 85 | 86 | ## Multiple Channels 87 | 88 | Multiple channels can be operated in parallel, and will do so independently of each other. 89 | 90 | Multiple commands can be sent at the same time, separated by a space character ‘ ‘, allowing instructions to be readied for multiple `L`, `R` & `V` channels before all are executed by the receipt of a `/n` character. Lag in scripted control can be minimised by sending the next instructions in advance, sending the new line to execute at the desired moment. 91 | 92 | Commands addressed to the same channel before a new line character is sent will overwrite previous buffered commands to that channel. 93 | 94 | ## Live Control 95 | 96 | To be able to keep up with a live feed, commands will need to have a short, quick fire format, for an instant response. 97 | 98 | For the fastest response possible during live control, each command should be followed immediately by a newline (`/n`). 99 | 100 | ## Device Commands 101 | 102 | Additional instructions to and from the device can be controlled through a predetermined list of commands prefixed with the letter `D` or `d`. 103 | 104 | Device Commands currently available: 105 | 106 | | Command | Action | 107 | | ------- | --------------------------------------------------------- | 108 | | `D0` | Identify device & firmware version | 109 | | `D1` | Identify TCode version | 110 | | `D2` | List available axes and associated user range preferences | 111 | | `DSTOP` | Stop device | 112 | 113 | ## Save commands 114 | 115 | To save a user's preferences to the EEPROM on the OSR2/SR6 on an axis-by-axis basis a save command can be used. These commands are prefixed by the symbol "$". 116 | 117 | These take the form `$TX-YYYY-ZZZZ` 118 | 119 | Where: 120 | 121 | `T` is the axis type (`L`, `R`, `V`, `A`) 122 | 123 | `X` is the axis number (`0`-`9`) 124 | 125 | `YYYY` is the preferred minimum (`0000`-`9999`) 126 | 127 | `ZZZZ` is the preferred maximum (`0000`-`9999`) 128 | 129 | Note that saved preferences do not change the behaviour of the device itself. They exist as a reference for the driving app or plugin, accessed via the D2 command. 130 | 131 | 132 | 133 | 134 | [axis diagram]: ./axes.png 135 | -------------------------------------------------------------------------------- /axes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/multiaxis/TCode-Specification/a809d2f39755a7d7b18df5f80ae7062668df83b4/axes.png --------------------------------------------------------------------------------