kst_reg.h File Reference

KST servo programming protocol: the register image and its fields. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "kst_wire.h"

Go to the source code of this file.

Data Structures
struct	kst_image_t
	The 32 registers, by address. More...
struct	kst_field_t
	One row of the field table. More...
struct	kst_fingerprint_t
	Broken rules and deviating registers of an image. More...

Macros
#define	KST_REG_DUTY_COPY   0x01u
	Register addresses that code outside the field table names.
#define	KST_REG_DUTY   0x02u
#define	KST_REG_NODE_ADDR   0x1Du
#define	KST_FIELD_BIT(id)
	The bit of field id in a kst_field_set_t.

Typedefs
typedef uint64_t	kst_field_set_t
	A set of fields, bit n for field n.

Enumerations
enum	kst_field_id_t {   KST_F_R00 = 0 , KST_F_DUTY_COPY , KST_F_DUTY , KST_F_BOOST ,   KST_F_STRETCH , KST_F_SOFT_START , KST_F_R04_B54 , KST_F_20K_SEL ,   KST_F_SPD_SEL , KST_F_DEAD_BAND , KST_F_LOCK , KST_F_ALLOW_UNCONT ,   KST_F_R06 , KST_F_PULSE_LOWER , KST_F_PULSE_UPPER , KST_F_NEUTRAL ,   KST_F_R0A_B5 , KST_F_REVERSION , KST_F_R0A_B7 , KST_F_UNCONT_POS ,   KST_F_R0D_B76 , KST_F_UNCONT_TIME , KST_F_R0F , KST_F_LEFT_ANGLE ,   KST_F_RIGHT_ANGLE , KST_F_R12_B20 , KST_F_PROT1_CANCLE , KST_F_R12_B54 ,   KST_F_PROT1_EN , KST_F_R12_B7 , KST_F_PROT1_TIME , KST_F_R14 ,   KST_F_PROT1_PWM , KST_F_R16 , KST_F_PROT_POT_ERR , KST_F_R18_B74 ,   KST_F_POT_SAM_TIMES , KST_F_PROT_PWM_ERR , KST_F_SPD , KST_F_R1C_B74 ,   KST_F_NODE_ADDR , KST_F_R1E , KST_F_GYRO , KST_F_R1F_B71 ,   KST_F_COUNT }
	Every bit of the 32 registers belongs to exactly one field. More...
enum	kst_access_t { KST_ACCESS_EDITABLE = 0 , KST_ACCESS_LOCKED , KST_ACCESS_NEVER }
	Who may change a field. More...
enum	kst_unit_t {   KST_UNIT_RAW = 0 , KST_UNIT_BOOL , KST_UNIT_TENTH_US , KST_UNIT_PERCENT ,   KST_UNIT_TENTH_PERCENT , KST_UNIT_TENTH_S , KST_UNIT_FACTOR , KST_UNIT_COUNT_OF }
	Unit of a displayed value. More...
enum	kst_type_t { KST_TYPE_V8 = 0 , KST_TYPE_V6 = 1 , KST_TYPE_NONE = 2 }
	The servo type of an image. More...
enum	kst_fp_rule_t {   KST_FP_R00 = 0 , KST_FP_DUTY_COPY , KST_FP_R06 , KST_FP_R1E ,   KST_FP_R04_B54 , KST_FP_R0A_B5_B7 , KST_FP_R12_UNNAMED , KST_FP_R1F_B71 ,   KST_FP_STRETCH_INDEX , KST_FP_COUNT }
	What both known images have in common and the vendor tool forces on every write. More...

Functions
const kst_field_t *	kst_field (kst_field_id_t id)
	The table row of id; NULL for an id outside the table.
uint16_t	kst_field_raw_max (kst_field_id_t id)
	Largest raw value the field's bits hold; 0 for an id outside the table.
uint8_t	kst_field_reg_mask (kst_field_id_t id, uint8_t reg)
	Bits of register reg that belong to id.
uint16_t	kst_field_get (const kst_image_t *img, kst_field_id_t id)
	Raw value of a field; 0 for a bad argument.
bool	kst_field_set (kst_image_t *img, kst_field_id_t id, uint16_t raw)
	Set a field's bits.
bool	kst_field_edit (kst_image_t *img, kst_field_id_t id, uint16_t raw)
	Set a field as an edit does: kst_field_set(), and for KST_F_DUTY the copy in register 0x01 as well.
bool	kst_field_display (kst_field_id_t id, uint16_t raw, int32_t *display)
	Raw value to displayed value.
bool	kst_field_raw_from_display (kst_field_id_t id, int32_t display, uint16_t *raw)
	Displayed value to the nearest raw value.
kst_type_t	kst_type (const kst_image_t *img)
	The type of img; KST_TYPE_NONE for NULL.
const char *	kst_type_name (kst_type_t type)
	"V8", "V6", and "" for any other value.
bool	kst_fingerprint (const kst_image_t *img, kst_fingerprint_t *out)
	True when the image has the measured layout.

Detailed Description

KST servo programming protocol: the register image and its fields.

Implements the programming protocol of KST and Chaservo servos. KST and Chaservo are names or trademarks of their respective owners; they are used here only to say which servos this module works with (README.md, "Legal notice and disclaimer").

A servo holds 32 registers of 8 bits. This file names every bit of them as a field, converts a field's raw value to the value the vendor tool shows and back, and checks an image against the layout the wire readings come from.

The image stores raw values. A displayed value is derived from the raw value and never written back on its own, so a field that is not edited keeps its bits. kst_field_set() changes the bits of one field and no other.

Displayed values are integers in the unit the field's kst_unit_t names. No floating point is used. Rounding, where a conversion rounds, is to the nearest value with a tie going up, except Max. Duty, whose tie goes down as the vendor tool's does (50% is raw 127).

The conversions are what the vendor tool displays and writes. The effect of a register on servo motion is not measured for any register. The scaling the vendor tool applies in Gyro Servo mode (register 0x1F bit 0: half the microsecond values, 0.05s time unit) is not applied here.

SPDX-License-Identifier: MIT

Macro Definition Documentation

KST_FIELD_BIT

#define KST_FIELD_BIT

(

id

)

Value:

((kst_field_set_t)1 << (id))

The bit of field id in a kst_field_set_t.

Enumeration Type Documentation

kst_access_t

enum kst_access_t

Who may change a field.

A decision about a field changes this column of the table and no code.

Enumerator
KST_ACCESS_EDITABLE	an edit may change it
KST_ACCESS_LOCKED	read-only until its function is measured; an unlock set passed to the checks lifts it
KST_ACCESS_NEVER	no edit path; only a restore writes it

kst_field_id_t

enum kst_field_id_t

Every bit of the 32 registers belongs to exactly one field.

Fields named KST_F_Rxx are bits the vendor tool gives no name.

Enumerator
KST_F_R00	not named by the vendor tool
KST_F_DUTY_COPY	01: the vendor tool writes the value of 02
KST_F_DUTY	02: Max. Duty
KST_F_BOOST	03
KST_F_STRETCH	04 bits 2-0
KST_F_SOFT_START	04 bit 3
KST_F_R04_B54	not named by the vendor tool
KST_F_20K_SEL	04 bit 6
KST_F_SPD_SEL	04 bit 7
KST_F_DEAD_BAND	05 bits 5-0
KST_F_LOCK	05 bit 6; meaning unknown
KST_F_ALLOW_UNCONT	05 bit 7
KST_F_R06	not named by the vendor tool
KST_F_PULSE_LOWER	07 and 09 bits 3-0
KST_F_PULSE_UPPER	08 and 09 bits 7-4
KST_F_NEUTRAL	0B and 0A bits 4-0
KST_F_R0A_B5	not named by the vendor tool
KST_F_REVERSION	0A bit 6
KST_F_R0A_B7	not named by the vendor tool
KST_F_UNCONT_POS	0C and 0D bits 3-0
KST_F_R0D_B76	not named by the vendor tool
KST_F_UNCONT_TIME	0E
KST_F_R0F	not named by the vendor tool
KST_F_LEFT_ANGLE	10
KST_F_RIGHT_ANGLE	11
KST_F_R12_B20	not named by the vendor tool
KST_F_PROT1_CANCLE	12 bit 3; the vendor's spelling
KST_F_R12_B54	not named by the vendor tool
KST_F_PROT1_EN	12 bit 6
KST_F_R12_B7	not named by the vendor tool
KST_F_PROT1_TIME	13 and 0D bits 5-4
KST_F_R14	not named by the vendor tool
KST_F_PROT1_PWM	15
KST_F_R16	not named by the vendor tool
KST_F_PROT_POT_ERR	17 and 18 bits 3-0
KST_F_R18_B74	not named by the vendor tool
KST_F_POT_SAM_TIMES	19
KST_F_PROT_PWM_ERR	1A
KST_F_SPD	1B and 1C bits 3-0
KST_F_R1C_B74	not named by the vendor tool
KST_F_NODE_ADDR	1D: the pairing value of the vendor's card
KST_F_R1E	not named by the vendor tool
KST_F_GYRO	1F bit 0: Servo or Gyro Servo
KST_F_R1F_B71	not named by the vendor tool

kst_fp_rule_t

enum kst_fp_rule_t

What both known images have in common and the vendor tool forces on every write.

An image that breaks one of these does not have the measured layout, and nothing is written to that servo.

Enumerator
KST_FP_R00	00 reads 00
KST_FP_DUTY_COPY	01 equals 02
KST_FP_R06	06 reads 04
KST_FP_R1E	1E reads 00
KST_FP_R04_B54	04 bits 5-4 are 0
KST_FP_R0A_B5_B7	0A bits 5 and 7 are 0
KST_FP_R12_UNNAMED	12 bits 0, 1, 2, 4, 5, 7 are 0
KST_FP_R1F_B71	1F bits 7-1 are 0
KST_FP_STRETCH_INDEX	the stretch index is 5 or less

kst_type_t

enum kst_type_t

The servo type of an image.

A servo answers no model number. The type is one bit: 20k_sel, register 04 bit 6. The manufacturer states the factory default of that bit as set for the V6.0 series (20kHz drive) and clear for the V8.0 series (333Hz drive). The mapping rests on that statement. It is read on 1 servo, whose bit is set; no V8.0 servo is measured. A servo whose 20k_sel was changed by another tool reads as the other type.

Enumerator
KST_TYPE_V8	20k_sel clear
KST_TYPE_V6	20k_sel set
KST_TYPE_NONE	no image, or a file that states no type

kst_unit_t

enum kst_unit_t

Unit of a displayed value.

Enumerator
KST_UNIT_RAW	the raw value, no unit known
KST_UNIT_BOOL	0 or 1
KST_UNIT_TENTH_US	0.1us
KST_UNIT_PERCENT	1%
KST_UNIT_TENTH_PERCENT	0.1%
KST_UNIT_TENTH_S	0.1s
KST_UNIT_FACTOR	a multiplier: 1, 2, 4, 8, 16, 32
KST_UNIT_COUNT_OF	a count: 0 to the field's width in bits

Function Documentation

kst_field()

const kst_field_t * kst_field

(

kst_field_id_t

id

)

The table row of id; NULL for an id outside the table.

Parameters

id

Field.

Returns

The table row, or NULL for an id outside the table.

kst_field_display()

bool kst_field_display	(	kst_field_id_t	id,
		uint16_t	raw,
		int32_t *	display )

Raw value to displayed value.

False where the displayed value of that raw value is not established: Stretch index 6 and 7.

Max. Duty round(raw x 100 / 255) % Boost 50us + 12.5us x raw Stretch 1 << index Dead Band 0.2us x (65 - raw) Pulse Lower, Pulse Upper, Uncontrolled Pos 0.8us x raw Neutral 810us + raw x 409 / 2048us, to 0.1us; the constants are a fit through 3 values and uncertain by about 1us Uncontrolled Time, prot1_time 0.1s x raw; prot1_time shown capped at 100.0s prot1_pwm round(raw x 97 / 255) % prot_pot_err, prot_pwm_err count of 1 bits upward from bit 0. The vendor tool shows 0 for registers 17 = FF, 18 = FF; here that image gives 12 SPD 0.1% x raw all others raw

Parameters

id	Field.
raw	Raw value.
display	Receives the displayed value.

Returns

true when the displayed value is established.

kst_field_edit()

bool kst_field_edit	(	kst_image_t *	img,
		kst_field_id_t	id,
		uint16_t	raw )

Set a field as an edit does: kst_field_set(), and for KST_F_DUTY the copy in register 0x01 as well.

Both known images hold 0x01 equal to 0x02.

Parameters

img	Image to change.
id	Field.
raw	Raw value.

Returns

true when the value fits and was stored.

kst_field_get()

uint16_t kst_field_get	(	const kst_image_t *	img,
		kst_field_id_t	id )

Raw value of a field; 0 for a bad argument.

Parameters

img	Image to read.
id	Field.

Returns

Raw value of the field; 0 for a NULL image or bad id.

kst_field_raw_from_display()

bool kst_field_raw_from_display	(	kst_field_id_t	id,
		int32_t	display,
		uint16_t *	raw )

Displayed value to the nearest raw value.

False when the value lies outside what the field encodes, when Stretch is not a power of two from 1 to 32, and for prot1_time and prot1_pwm, whose encoding on write is not observed.

Parameters

id	Field.
display	Displayed value.
raw	Receives the raw value.

Returns

true when a raw value gives this display value.

kst_field_raw_max()

uint16_t kst_field_raw_max

(

kst_field_id_t

id

)

Largest raw value the field's bits hold; 0 for an id outside the table.

Parameters

id

Field.

Returns

Largest raw value the field holds; 0 for an id outside the table.

kst_field_reg_mask()

uint8_t kst_field_reg_mask	(	kst_field_id_t	id,
		uint8_t	reg )

Bits of register reg that belong to id.

Parameters

id	Field.
reg	Register address.

Returns

Bits of reg that belong to id.

kst_field_set()

bool kst_field_set	(	kst_image_t *	img,
		kst_field_id_t	id,
		uint16_t	raw )

Set a field's bits.

No other bit of the image changes. False, and no change, when raw does not fit the field.

Parameters

img	Image to change.
id	Field.
raw	Raw value.

Returns

true when the value fits and was stored.

kst_fingerprint()

bool kst_fingerprint	(	const kst_image_t *	img,
		kst_fingerprint_t *	out )

True when the image has the measured layout.

out may be NULL.

Parameters

img	Image to check.
out	Receives the broken rules and deviating registers; may be NULL.

Returns

true when the image has the measured layout.

kst_type()

kst_type_t kst_type

(

const kst_image_t *

img

)

The type of img; KST_TYPE_NONE for NULL.

Parameters

img	Image to read.

Returns

The servo type; KST_TYPE_NONE for NULL.

kst_type_name()

const char * kst_type_name

(

kst_type_t

type

)

"V8", "V6", and "" for any other value.

Parameters

type	Servo type.

Returns

"V8", "V6", or "" for any other value.