<!-- Source: https://medius.k4tech.net/native/commands/inject -->
# Inject

_Press and release any input_

[`INJECT`](/native/commands/inject.md#inject) sets a momentary input on top of whatever the user is physically doing: a mouse [button](/native/commands/inject.md#button), a keyboard [key](/native/commands/inject.md#key) or modifier, or a [media](/native/commands/inject.md#media) key. One verb covers all three, tagged by a `class` byte, so the same press / release logic works for every input class. The continuous axes (cursor and wheel) have their own verb, [`MOVE`](/native/commands/move.md#move).

## INJECT

_Momentary-usage override_

`INJECT` sets a per-usage [override](/native/injection.md#state), the box's own held decision layered over the physical input. The `class` byte picks the input kind, `id` picks the usage within that class, and `action` is the same tri-state for all three. [Opcode](/native/frame.md#opcodes) `0x03`.

```text
INJECT 0x03 · payload 4 bytes
```

_Fire-and-forget_

#### PAYLOAD

| Offset | Field | Type | Notes |
| --- | --- | --- | --- |
| 0 | `class` | `u8` | 0=button 1=key 2=media (the input kind) |
| 1 | `id` | `u16` | the usage within the class, little-endian (see each class below) |
| 3 | `action` | `u8` | 0=soft-release 1=press 2=force-release |

#### CLASSES

| Class | Value | `id` is |
| --- | --- | --- |
| [button](/native/commands/inject.md#button) | `0` | a semantic [button id](/native/commands/usage.md#buttons) (0=Left .. 4=Side2) |
| [key](/native/commands/inject.md#key) | `1` | a [HID keyboard usage](/native/commands/usage.md#keycodes) (0xE0-0xE7 = modifier) |
| [media](/native/commands/inject.md#media) | `2` | a 16-bit [Consumer usage](/native/commands/usage.md#consumer) |

#### ACTIONS

| Action | Value | Effect |
| --- | --- | --- |
| press | `1` | Force the usage active regardless of physical state. |
| soft-release | `0` | Drop our override (whether it was a press or a force-release); a physical hold stays active. |
| force-release | `2` | Force the usage inactive, masking a physical hold too. The release the [safety auto-clear](/native/injection.md#safety) uses. |

#### RESULT THE PC SEES

The two releases differ only when the user is physically holding the same input:

| Action | User holds nothing | User is holding it |
| --- | --- | --- |
| `press` | active | active |
| `soft-release` | inactive | active (physical wins) |
| `force-release` | inactive | inactive (masks physical) |

#### RULES

```
additive   layers over the user at the same merge point as MOVE;
           never evicts the user's own input
no click   no firmware click or chord; send a press, then your
           own client-timed soft-release
RESET      releases every override at once
```

> **Warning**
>
> A usage the cloned device can't report is a silent no-op. Check [`CAPS`](/native/commands/requests.md#caps) before you rely on it.

Library binding: [`inject`](/library/inject.md#inject).

## class = button

_Mouse button override_

With `class = 0`, `id` is a semantic [button id](/native/commands/usage.md#buttons) (0=Left, 1=Right, 2=Middle, 3=Side1, 4=Side2), bound at clone time to the real mouse's buttons. The override sets that button's bit in the report the PC sees. Library bindings: [`inject` / `press` / `release` / `force_release`](/library/inject.md#inject).

#### EXAMPLE

Press Left: `class` `0x00`, `id` `0x0000`, `action` `0x01`:

```
+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 03     | 00     | 04 00  | 00     | 00 00  | 01     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | class  | id     | action | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+
```

## class = key

_Keyboard key and modifier override_

With `class = 1`, `id` is a [HID keyboard usage](/native/commands/usage.md#keycodes). A usage of `0xE0`\-`0xE7` folds into the modifier byte; anything else fills a keycode slot (or sets its NKRO bit) in the report the PC sees. Physical keys keep their slots, so injection never evicts the user's typing; past the board's rollover limit it emits the board's own `ErrorRollOver`. A keycode the cloned board can't report is a no-op. Library bindings: [`inject` / `press` / `release` / `force_release`](/library/inject.md#inject).

#### EXAMPLE

Press `A`: `class` `0x01`, `id` `0x0004`, `action` `0x01`:

```
+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 03     | 00     | 04 00  | 01     | 04 00  | 01     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | class  | id     | action | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+
```

## class = media

_Media key override_

With `class = 2`, `id` is a 16-bit [Consumer usage](/native/commands/usage.md#consumer) (e.g. 0xCD Play/Pause, 0xE9 Volume Up), merged onto the cloned keyboard's Consumer report. Present-gated to a board that declares a Consumer collection, read from the [`CAPS`](/native/commands/requests.md#caps) `CONSUMER` flag; otherwise a no-op. Library bindings: [`inject` / `press` / `release` / `force_release`](/library/inject.md#inject).

#### EXAMPLE

Press Volume Up: `class` `0x02`, `id` `0x00E9`, `action` `0x01`:

```
+--------+--------+--------+--------+--------+--------+--------+--------+
| A5     | 03     | 00     | 04 00  | 02     | E9 00  | 01     | lo hi  |
+--------+--------+--------+--------+--------+--------+--------+--------+
| SOF    | TYPE   | SEQ    | LEN    | class  | id     | action | CRC16  |
+--------+--------+--------+--------+--------+--------+--------+--------+
```