soarers_converter/docs/config.html

259 lines
9.2 KiB
HTML

<html>
<head>
<link rel="stylesheet" type="text/css" href="style1.css">
<title>XT/AT/PS2/Terminal to USB Converter with NKRO - Config</title>
</head>
<body>
<script type="text/javascript" src="headermenu.js"></script>
<script type="text/javascript">navtabfn("Config")</script>
<noscript><div id=jswarn class=\"navtabs\">These docs work best with Javascript enabled!</div></noscript>
<h2>Config <span class="versioninfo">v0.997+</span></h2>
<hr>
<div id="contentslist">
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#commands">Command Reference</a></li>
<ul>
<li><a href="#force">force</a></li>
<li><a href="#include">include</a></li>
<li><a href="#ifselect">ifselect</a></li>
<li><a href="#ifset">ifset</a></li>
<li><a href="#ifkeyboard">ifkeyboard</a></li>
<li><a href="#remapblock">remapblock</a></li>
<li><a href="#layerblock">layerblock</a></li>
<li><a href="#macroblock">macroblock</a></li>
<ul>
<li><a href="#macro_commands">Macro Commands</a></li>
<li><a href="#triggers">Macro trigger matching</a></li>
</ul>
</ul>
</ul>
</div>
<h3><a name="overview">Overview</a></h3>
<hr>
<p>This diagram gives an simplified view of the processing stages inside the converter:<br>
<img src="images/dataflow.png"/></p>
<p>The first stage is a fixed translation into HID codes, that cannot be modified by the config. The goal of this stage is
to map into a reasonable base set of codes for further remapping, and to try and ensure that each key on the keyboard
results in a unique HID code after this stage.</p>
<p>The second stage combines remapping and layer functions, since layers are simply alternate remappings.</p>
<p>The third stage is macro expansion.</p>
<p>The final stage separates out the internal commands such as SELECTn and BOOT etc. and routes them appropriately, and
also converts the HIDX codes back into standard HID codes for the keyboard, media, and power code pages.</p>
<h3><a name="commands">Command Reference</a></h3>
<hr>
<h4><a name=force></a>force</h4>
<hr>
<p>The <code>force</code> command disables the auto-detection of keyboard type. It is only very rarely needed!</p>
<pre><code>force {set1|set2|set3|set2ext}
</code></pre>
<p>Example:</p>
<pre><code>force set2
</code></pre>
<h4><a name=include></a>include</h4>
<hr>
<p>The <code>include</code> command processes another file, exactly as if it was copy-pasted to where the include command is.</p>
<pre><code>include &lt;file_name&gt;
</code></pre>
<p>Quotation marks are optional unless the file name contains spaces.</p>
<p>Example:</p>
<pre><code>include "colemak.sc"
</code></pre>
<h4><a name=ifselect></a>ifselect</h4>
<hr>
<p>
Groups of settings can be toggled by using the <code>ifselect</code> command and defining remaps or macros that output the SELECT_0 to SELECT_7 codes.</p>
<pre><code>ifselect {&lt;select_num&gt; | any}
</code></pre>
<p>
When any of the SELECT codes are output the entire config is reloaded, and the <code>ifselect</code> commands choose which blocks will be applied.<br/>
When the converter powers-up, all selects, except select 0, are inactive.<br/>
Multiple selects can be active at a time.<br/>
Select 0 is special - it is always active, and when SELECT_0 is output it resets all the other selects.
</p>
<p>Blocks following <code>ifselect &lt;select_num&gt;</code>, up to the next <code>ifselect</code>, are applied only if the specified select is active.</p>
<p>Blocks following <code>ifselect any</code>, up to the next <code>ifselect</code>, are applied regardless of which selects are active.</p>
<p>Example:</p>
<pre><code># toggle between qwerty and colemak by pressing scroll lock
ifselect 1
include colemak.sc
ifselect any
remapblock
SCROLL_LOCK SELECT_1
endblock
</code></pre>
<h4><a name=ifset></a>ifset</h4>
<hr>
<p>Blocks following the <code>ifset</code> command are only applied if using one of the specified sets.</p>
<pre><code>ifset [set1] [set2] [set3] [set2ext] [any]
</code></pre>
<p>Example:</p>
<pre><code>ifset set1 set2
</code></pre>
<h4><a name=ifkeyboard></a>ifkeyboard</h4>
<hr>
<p>Blocks following the <code>ifkeyboard</code> command are only applied if the keyboard has the specified ID.</br>
<pre><code>ifkeyboard {&lt;keyboard_id&gt; | any}
</code></pre>
<p>The keyboard ID is given in hexadecimal.</p>
<p>See the <a href=trouble.html#keyboardid>Troubleshooting</a> section for details of how to find out the ID of your keyboard.</p>
<p>Example:</p>
<pre><code>ifkeyboard BABA
</code></pre>
<h4><a name=layerblock></a>layerblock</h4>
<hr>
<p>Layerblocks define combinations of function keys to access different layers.</p>
<pre><code>layerblock
&lt;fn_key_combo&gt; &lt;layer_num&gt;
...
endblock
</code></pre>
<p>Function keys are defined by remapping keys to codes FN1 to FN8.</p>
<p>Example:</p>
<pre><code>layerblock
FN1 1
FN2 1
FN1 FN2 2
endblock
<a href=config.html#remapblock>remapblock</a>
LGUI FN1
RGUI FN2
endblock
</code></pre>
<h4><a name=remapblock></a>remapblock</h4>
<hr>
<p>Remapblocks define remappings either for the base layer, or for the specified
layer if a <code>layer</code> command is given inside the block.</p>
<pre><code>remapblock
[layer &lt;layer_num&gt;]
&lt;from_hid&gt; &lt;to_hid&gt;
...
endblock
</code></pre>
<p>Example:</p>
<pre><code># swap capslock and backspace
remapblock
CAPS_LOCK BACKSPACE
BACKSPACE CAPS_LOCK
endblock
</code></pre>
<h4><a name=macroblock></a>macroblock</h4>
<hr>
<p>Macroblocks define one or more macros. Macros are triggered by a single HID
key with any combination of metas, and can have command blocks that execute
on make and/or break of the HID key.</p>
<pre><code>macroblock
macro &lt;hid&gt; [[-][{l|r}]shift] [[-][{l|r}]ctrl] [[-][{l|r}]alt] [[-][{l|r}]gui] ...
[
&lt;command&gt; [&lt;value&gt;]
...
]
[onbreak [norestoremeta]
&lt;command&gt; [&lt;value&gt;]
...
]
endmacro
...
endblock
</code></pre>
<p>Example:</p>
<pre><code>macroblock
macro SCROLL_LOCK LSHIFT LCTRL -ALT
PUSH_META CLEAR_META all # save and clear all metas
PRESS p # press some keys...
PRESS i
PRESS N # case is ignored - this results in lowercase 'n'
SET_META lshift # you have to set modifiers yourself
PRESS g # results in a capital 'G', since shift is set
POP_ALL_META # restore metas that were active before
endmacro
endblock
</code></pre>
<h5><a name="macro_commands">Macro Commands</a></h5>
<table>
<tr><th>Command</th><th>Description</th></tr>
<tr><td>NOP</td><td>Does nothing</td></tr>
<tr><td>PRESS &lt;hid&gt;</td><td>Shorthand for MAKE &lt;hid&gt; then BREAK &lt;hid&gt;</td></tr>
<tr><td>MAKE &lt;hid&gt;</td><td>Set keystate to 'down'</td></tr>
<tr><td>BREAK &lt;hid&gt;</td><td>Set keystate to 'up'</td></tr>
<tr><td>ASSIGN_META &lt;metas&gt;</td><td>Set all metas to the state specified</td></tr>
<tr><td>SET_META &lt;metas&gt;</td><td>Set specified metas to down state</td></tr>
<tr><td>CLEAR_META &lt;metas&gt;</td><td>Set specified metas to up state</td></tr>
<tr><td>TOGGLE_META &lt;metas&gt;</td><td>Set specified metas to inverse of current state</td></tr>
<tr><td>POP_META</td><td>Restore metas from the time of the last PUSH_META</td></tr>
<tr><td>POP_ALL_META</td><td>Restore metas from the time of the first PUSH_META</td></tr>
<tr><td>DELAY &lt;delay_in_ms&gt;</td><td>Delay by the specified number of milliseconds</td></tr>
<tr><td>CLEAR_ALL</td><td>(internal use e.g. when buffer overrun is received)</td></tr>
<tr><td>BOOT</td><td>Cause the converter to jump to the bootloader <span class="versioninfo">v1.0+</span></td></tr>
<tr><td>PUSH_META &lt;cmd&gt; &lt;value&gt;</td><td>Save metas for later. Combines with other commands</td></tr>
</table>
<h5><a name="triggers">Macro trigger matching</a></h5>
<p>
Macros are triggered only when the state matches for all of the the specified metas.<br/>
If a particular meta is not specified, its state is not matched.<br/>
</p>
<table>
<tr><th>Meta</th><th>Trigger condition</th></tr>
<tr><td>LSHIFT</td><td>LSHIFT is pressed</td></tr>
<tr><td>RSHIFT</td><td>RSHIFT is pressed</td></tr>
<tr><td>SHIFT</td><td>Either LSHIFT or RSHIFT is pressed</td></tr>
<tr><td>-LSHIFT</td><td>LSHIFT is not pressed</td></tr>
</table>
<p>
When looking for a match, macros are checked in the order they appear in the config file.<br/>
The first matching macro found (if any) is executed, so you sometimes need to take of what order the macros are in.
</p>
<pre><code>macroblock
macro SCROLL_LOCK LSHIFT # this macro will execute even if LCTRL is down, so...
...
endmacro
macro SCROLL_LOCK LSHIFT LCTRL # ... this macro will never execute!
...
endmacro
endblock
</code></pre>
<p>The correct order would be:</p>
<pre><code>macroblock
macro SCROLL_LOCK LSHIFT LCTRL
...
endmacro
macro SCROLL_LOCK LSHIFT
...
endmacro
endblock
</code></pre>
<p>See the <a href="codes.html">HID code list</a> for HID and META values.</p>
<hr>
</body></html>