kst_limits.h File Reference

KST servo programming protocol: limits on an edited image. More...

#include <stdbool.h>
#include <stdint.h>
#include "kst_reg.h"

Go to the source code of this file.

Macros
#define	KST_DUTY_RAW_MAX   250u
	Raw limits.
#define	KST_DUTY_RAW_MIN   26u
#define	KST_DUTY_RAW_HALF   128u
#define	KST_DUTY_RAW_90   230u
#define	KST_BOOST_RAW_MAX   236u
#define	KST_STRETCH_INDEX_MAX   5u
#define	KST_SPD_RAW_MAX   1000u
#define	KST_SPD_RAW_MIN_ON   50u
#define	KST_SPD_RAW_SLOW   300u
#define	KST_DEAD_BAND_RAW_1US   60u
#define	KST_PULSE_RAW_MIN   625u
#define	KST_PULSE_RAW_MAX   3125u
#define	KST_NEUTRAL_RAW_MIN   2754u
#define	KST_NEUTRAL_RAW_MAX   4156u
#define	KST_UNCONT_TIME_RAW_MIN   4u
#define	KST_UNCONT_TIME_RAW_MAX   130u
#define	KST_UNCONT_TIME_RAW_SHORT   10u
#define	KST_ANGLE_RAW_SMALL   50u
#define	KST_MARGIN_HARD_TENTH_US   1000
	Distances between pulse widths, in 0.1us.
#define	KST_MARGIN_SOFT_TENTH_US   3000
#define	KST_SPAN_MIN_TENTH_US   4000
#define	KST_END_MOVE_TENTH_US   1000
#define	KST_NEUTRAL_MOVE_TENTH_US   200
#define	KST_UNCONT_FAR_TENTH_US   3000
#define	KST_RULE_BIT(rule)
#define	KST_RULES_HARD   (KST_RULE_BIT(KST_S_DUTY_RAISED) - 1u)
	The hard rules as a set.

Typedefs
typedef uint64_t	kst_rules_t
	A set of rules, bit n for rule n.

Enumerations
enum	kst_rule_t {   KST_H_DUTY_HIGH = 0 , KST_H_DUTY_LOW = 1 , KST_H_DUTY_COPY = 2 , KST_H_BOOST_HIGH = 3 ,   KST_H_STRETCH_INDEX = 4 , KST_H_SPD_HIGH = 5 , KST_H_SPD_SEL_LOW_SPD = 6 , KST_H_UNCONT_POS_LOW = 7 ,   KST_H_UNCONT_POS_HIGH = 8 , KST_H_UNCONT_POS_SPAN = 9 , KST_H_UNCONT_TIME_LOW = 10 , KST_H_UNCONT_TIME_HIGH = 11 ,   KST_H_LOWER_LOW = 12 , KST_H_LOWER_MARGIN = 13 , KST_H_UPPER_HIGH = 14 , KST_H_UPPER_MARGIN = 15 ,   KST_H_SPAN = 16 , KST_H_NEUTRAL_LOW = 17 , KST_H_NEUTRAL_HIGH = 18 , KST_H_LEFT_ZERO = 19 ,   KST_H_RIGHT_ZERO = 20 , KST_H_GYRO_MODE = 21 , KST_H_LOCKED = 22 , KST_H_NEVER = 23 ,   KST_S_DUTY_RAISED = 24 , KST_S_DUTY_BELOW_HALF = 25 , KST_S_BOOST_RAISED = 26 , KST_S_STRETCH_RAISED = 27 ,   KST_S_SOFT_START_OFF = 28 , KST_S_SPD_SEL_ON = 29 , KST_S_SPD_SLOW = 30 , KST_S_DEAD_BAND_NARROWED = 31 ,   KST_S_DEAD_BAND_BELOW_1US = 32 , KST_S_ALLOW_UNCONT_ON = 33 , KST_S_UNCONT_POS_FAR = 34 , KST_S_UNCONT_TIME_SHORT = 35 ,   KST_S_LOWER_NEAR = 36 , KST_S_LOWER_MOVED = 37 , KST_S_UPPER_NEAR = 38 , KST_S_UPPER_MOVED = 39 ,   KST_S_NEUTRAL_MOVED = 40 , KST_S_REVERSION_CHANGED = 41 , KST_S_LEFT_RAISED = 42 , KST_S_LEFT_SMALL = 43 ,   KST_S_RIGHT_RAISED = 44 , KST_S_RIGHT_SMALL = 45 , KST_S_GYRO_CHANGED = 46 , KST_S_NARROW_BAND_GAIN = 47 ,   KST_S_HIGH_DUTY_TRAVEL = 48 , KST_RULE_COUNT = 49 }
	The rules. More...

Functions
kst_rules_t	kst_limits_image (const kst_image_t *img)
	The hard rules an image breaks on its own.
kst_rules_t	kst_limits_edit (const kst_image_t *backup, const kst_image_t *target, kst_field_set_t unlocked, kst_field_set_t *refused)
	The hard and soft rules the image target breaks as an edit of the servo's image backup.

Detailed Description

KST servo programming protocol: limits on an edited image.

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 hard rule refuses an image. A soft rule asks for a confirmation and never refuses. Each rule has an identifier that stays the same across versions, so a user interface maps it to a text.

The hard limits are the ranges the vendor tool prints on its controls, the encodings that are not established and the states with no control authority. The soft limits mark values inside the vendor's range that move away from the servo's own backed-up value in the hazardous direction. The numbers marked "proposed" have no measurement behind them. What a register does to the servo's motion is not measured for any register, so the limits rest on the vendor's labels.

The limits cannot see the mechanical travel of a gear train, a linkage, the supply or the load.

SPDX-License-Identifier: MIT

Macro Definition Documentation

KST_ANGLE_RAW_SMALL

#define KST_ANGLE_RAW_SMALL   50u

proposed

KST_BOOST_RAW_MAX

#define KST_BOOST_RAW_MAX   236u

3000us

KST_DEAD_BAND_RAW_1US

#define KST_DEAD_BAND_RAW_1US   60u

1.0us; a higher raw value is narrower

KST_DUTY_RAW_90

#define KST_DUTY_RAW_90   230u

the highest raw value shown as 90%

KST_DUTY_RAW_HALF

#define KST_DUTY_RAW_HALF   128u

50%, proposed

KST_DUTY_RAW_MAX

#define KST_DUTY_RAW_MAX   250u

Raw limits.

Pulse widths: 1 count is 0.8us. 98%

KST_DUTY_RAW_MIN

#define KST_DUTY_RAW_MIN   26u

10%, proposed

KST_END_MOVE_TENTH_US

#define KST_END_MOVE_TENTH_US   1000

an end point against the backup: 100us

KST_MARGIN_HARD_TENTH_US

#define KST_MARGIN_HARD_TENTH_US   1000

Distances between pulse widths, in 0.1us.

All proposed. Neutral to an end point: 100us

KST_MARGIN_SOFT_TENTH_US

#define KST_MARGIN_SOFT_TENTH_US   3000

Neutral to an end point: 300us

KST_NEUTRAL_MOVE_TENTH_US

#define KST_NEUTRAL_MOVE_TENTH_US   200

Neutral against the backup: 20us

KST_NEUTRAL_RAW_MAX

#define KST_NEUTRAL_RAW_MAX   4156u

1640us

KST_NEUTRAL_RAW_MIN

#define KST_NEUTRAL_RAW_MIN   2754u

1360us

KST_PULSE_RAW_MAX

#define KST_PULSE_RAW_MAX   3125u

2500us

KST_PULSE_RAW_MIN

#define KST_PULSE_RAW_MIN   625u

500us

KST_RULE_BIT

#define KST_RULE_BIT

(

rule

)

Value:

((kst_rules_t)1 << (rule))

KST_SPAN_MIN_TENTH_US

#define KST_SPAN_MIN_TENTH_US   4000

Upper less Lower: 400us

KST_SPD_RAW_MAX

#define KST_SPD_RAW_MAX   1000u

100%

KST_SPD_RAW_MIN_ON

#define KST_SPD_RAW_MIN_ON   50u

5% with spd_sel on, proposed

KST_SPD_RAW_SLOW

#define KST_SPD_RAW_SLOW   300u

30% with spd_sel on, proposed

KST_STRETCH_INDEX_MAX

#define KST_STRETCH_INDEX_MAX   5u

factor 32

KST_UNCONT_FAR_TENTH_US

#define KST_UNCONT_FAR_TENTH_US   3000

Uncontrolled Pos from Neutral: 300us

KST_UNCONT_TIME_RAW_MAX

#define KST_UNCONT_TIME_RAW_MAX   130u

13.0s

KST_UNCONT_TIME_RAW_MIN

#define KST_UNCONT_TIME_RAW_MIN   4u

0.4s

KST_UNCONT_TIME_RAW_SHORT

#define KST_UNCONT_TIME_RAW_SHORT   10u

1.0s, proposed

Enumeration Type Documentation

kst_rule_t

enum kst_rule_t

The rules.

Values are stable: a rule keeps its number, a new rule takes the next free one. KST_H_ rules are hard, KST_S_ rules are soft.

Enumerator
KST_H_DUTY_HIGH	Max. Duty above 98%
KST_H_DUTY_LOW	Max. Duty below 10%
KST_H_DUTY_COPY	register 01 differs from 02
KST_H_BOOST_HIGH	Boost above 3000us
KST_H_STRETCH_INDEX	Stretch index 6 or 7
KST_H_SPD_HIGH	SPD above 100%
KST_H_SPD_SEL_LOW_SPD	spd_sel on with SPD below 5%
KST_H_UNCONT_POS_LOW	Uncontrolled Pos below 500us
KST_H_UNCONT_POS_HIGH	Uncontrolled Pos above 2500us
KST_H_UNCONT_POS_SPAN	Uncontrolled Pos outside Lower..Upper
KST_H_UNCONT_TIME_LOW	Uncontrolled Time below 0.4s
KST_H_UNCONT_TIME_HIGH	Uncontrolled Time above 13.0s
KST_H_LOWER_LOW	Pulse Lower below 500us
KST_H_LOWER_MARGIN	Neutral less Lower below 100us
KST_H_UPPER_HIGH	Pulse Upper above 2500us
KST_H_UPPER_MARGIN	Upper less Neutral below 100us
KST_H_SPAN	Upper less Lower below 400us
KST_H_NEUTRAL_LOW	Neutral below 1360us
KST_H_NEUTRAL_HIGH	Neutral above 1640us
KST_H_LEFT_ZERO	Left Angle 0
KST_H_RIGHT_ZERO	Right Angle 0
KST_H_GYRO_MODE	Gyro Servo mode: its limits are not known
KST_H_LOCKED	a locked field differs from the backup
KST_H_NEVER	a field with no edit path differs
KST_S_DUTY_RAISED	Max. Duty above the backup
KST_S_DUTY_BELOW_HALF	Max. Duty below 50%
KST_S_BOOST_RAISED	Boost above the backup
KST_S_STRETCH_RAISED	Stretch above the backup
KST_S_SOFT_START_OFF	Soft_Start switched off
KST_S_SPD_SEL_ON	spd_sel switched on
KST_S_SPD_SLOW	SPD below 30% with spd_sel on
KST_S_DEAD_BAND_NARROWED	Dead Band below the backup
KST_S_DEAD_BAND_BELOW_1US	Dead Band below 1.0us
KST_S_ALLOW_UNCONT_ON	Allow Uncont switched on
KST_S_UNCONT_POS_FAR	more than 300us from Neutral, Allow Uncont on
KST_S_UNCONT_TIME_SHORT	Uncontrolled Time below 1.0s
KST_S_LOWER_NEAR	Neutral less Lower below 300us
KST_S_LOWER_MOVED	Pulse Lower more than 100us from the backup
KST_S_UPPER_NEAR	Upper less Neutral below 300us
KST_S_UPPER_MOVED	Pulse Upper more than 100us from the backup
KST_S_NEUTRAL_MOVED	Neutral more than 20us from the backup
KST_S_REVERSION_CHANGED	Reversion differs from the backup
KST_S_LEFT_RAISED	Left Angle above the backup
KST_S_LEFT_SMALL	Left Angle below 50
KST_S_RIGHT_RAISED	Right Angle above the backup
KST_S_RIGHT_SMALL	Right Angle below 50
KST_S_GYRO_CHANGED	Servo / Gyro Servo differs from the backup
KST_S_NARROW_BAND_GAIN	Dead Band below 1.0us with Stretch above 1 or Boost above the backup
KST_S_HIGH_DUTY_TRAVEL	Max. Duty above 90% with an angle above the backup

Function Documentation

kst_limits_edit()

kst_rules_t kst_limits_edit	(	const kst_image_t *	backup,
		const kst_image_t *	target,
		kst_field_set_t	unlocked,
		kst_field_set_t *	refused )

The hard and soft rules the image target breaks as an edit of the servo's image backup.

unlocked lifts KST_ACCESS_LOCKED for the fields in it. Nothing lifts KST_ACCESS_NEVER; register 01 may follow 02. refused, when not NULL, receives the changed fields that the access class refuses.

A soft rule about a value on its own (KST_S_DUTY_BELOW_HALF and the like) is reported when the edit changes a field the rule reads, not for a state the servo already has.

Parameters

backup	Image the edit starts from.
target	Image after the edit.
unlocked	Fields whose KST_ACCESS_LOCKED is lifted.
refused	Receives the refused fields; may be NULL.

Returns

The hard and soft rules the edit breaks.

kst_limits_image()

kst_rules_t kst_limits_image

(

const kst_image_t *

img

)

The hard rules an image breaks on its own.

Pulse Lower, Upper and Uncontrolled Pos are compared with Neutral in microseconds, because Neutral's unit differs from theirs.

An image in Gyro Servo mode breaks KST_H_GYRO_MODE: the vendor tool halves every microsecond value there, and what a servo does with them is not measured.

Parameters

img	Image to check.

Returns

The hard rules the image breaks; KST_RULES_HARD for NULL.