# AK 2.0 and manual v1.0.18

This library targets the **AK-DRV-V2.1** driver and *AK Series Module Driver Manual*
**v1.0.18** (2026-01-19). Most existing Python libraries were written against AK 1.0-era
firmware and an older manual.

## What changed that matters

**New motors.** v1.0.17 added AK45-36, AK45-10 and **AK40-10**; v1.0.18 corrected the
AK45-10 parameters. Libraries predating these simply do not have the field ranges.

**A new fault code.** Code 7 is motor stall. Code 6 is MOSFET over-temperature — older
libraries label it "phase current unbalance", which is wrong. Indexing a 0–6 dict with a 7
raises `KeyError`, and in the reference library that happens inside the receive thread
where it is swallowed.

**Corrected position-velocity scaling.** v1.0.12 fixed the byte-order description and
v1.0.14 corrected the origin-mode and position-velocity routines. The CAN `SET_POS_SPD`
packet divides speed *and* acceleration by 10 before packing them as `int16`.

**Permanent zero is dual-encoder only.** v1.0.15 spelled this out. Origin mode 1 writes
flash; on a single-encoder model such as the AK40-10 it is meaningless.

**Two fault tables, not one.** CAN feedback uses codes 0–7. The serial `GET_VALUES` reply
uses `mc_fault_code`, where 1 is over-voltage and the range runs to 18. They are not
interchangeable.

## Protocol facts worth having in one place

MIT command — **standard** frame, arbitration id = motor id, DLC 8:

```
D0 = p>>8              D1 = p & 0xFF
D2 = v>>4              D3 = (v & 0xF)<<4 | kp>>8
D4 = kp & 0xFF         D5 = kd>>4
D6 = (kd & 0xF)<<4 | t>>8    D7 = t & 0xFF
```

MIT reply — standard frame, DLC 8: `D0` driver id, `D1..D2` position (16 bit),
`D3`+`D4` high nibble velocity (12 bit), `D4` low nibble +`D5` torque (12 bit),
`D6` temperature + 40, `D7` fault.

Special MIT payloads: enter `FF×7,FC`, exit `FF×7,FD`, zero `FF×7,FE`.

Servo — **extended** frame, `arbitration_id = (packet_id << 8) | motor_id`:

| Packet | id | Payload | Scale |
|---|---|---|---|
| SET_DUTY | 0 | int32 | duty × 1e5 |
| SET_CURRENT | 1 | int32 | A × 1000 |
| SET_CURRENT_BRAKE | 2 | int32 | A × 1000, ≥ 0 |
| SET_RPM | 3 | int32 | raw ERPM |
| SET_POS | 4 | int32 | **deg × 1e4** |
| SET_ORIGIN | 5 | uint8 | 0 temporary, 1 permanent |
| SET_POS_SPD | 6 | int32 + int16 + int16 | deg × 1e4; **spd/10**; **acc/10** |
| SET_MIT | 8 | undocumented | in the enum, no payload given — not implemented |

Servo replies, by function id `(arb_id >> 8) & 0xFF`:

| id | meaning |
|---|---|
| `0x29` | state |
| `0x2C` | entered servo mode, payload `FA FB FC FD` |
| `0x09` | jump to bootloader |

Only `0x29` is state. Decoding `0x2C` as a position yields a plausible-looking −128.5°.

## The float↔uint asymmetry

The manual's `float_to_uint` uses `(1<<bits)/span` and its `uint_to_float` uses
`span/((1<<bits)-1)`. These are not inverses, and the pack direction **overflows the field
at exactly x_max**: 12.5 rad maps to 65536, which does not fit in 16 bits.

This library uses `((1<<bits)-1)/span` with rounding — the exact inverse of the documented
unpack, never overflowing, and within 1 LSB of the manual's formula everywhere else. The
simulator can decode either way (`ScalingVariant.EXACT` / `TRUNCATED`) so commands are
verified correct against both possible firmware readings.

## Saturated commands collide with mode-control frames

With position, velocity, Kp and Kd all at maximum:

| torque | packs to | driver reads it as |
|---|---|---|
| 4.99267 N·m | `FF … FC` | enter MIT mode |
| 4.99512 N·m | `FF … FD` | exit MIT mode |
| 4.99756 N·m | `FF … FE` | **set position to zero** |

A controller winding up against its limits can reach that band, and a mid-motion re-zero
moves the position reference out from under the loop. `pack_command` steps one torque LSB
away — 2.4 mN·m, far below anything the motor can resolve.