Stick programming: what can run. More...

#include "esc_stick.h"
#include "esc_stick_int.h"
#include <string.h>

Functions
esc_throttle_t	esc_stick_listen (const esc_profile_t *p)
	Where the stick rests while the menu sounds: the profile's listen move, else where the entry left it.
float	esc_stick_pct (esc_throttle_t pos)
	A throttle position as the output's percentage.
static bool	values_repeat (const esc_profile_t *p)
	Whether any value number appears in two items.
static bool	hand_fits (const esc_profile_t *p)
	Whether every manual step can be waited for.
static bool	value_holds (const esc_profile_t *p)
	Whether a value states its own entry time: the profile-wide rest rule leaves such a profile to the per-change one (entry_refused()), which sees the value's time.
static const esc_manual_t *	menu_start (const esc_profile_t *p)
	The step that starts the menu, or NULL.
static esc_stick_kind_t	refuse (const char *why, const char text)
	Set the refusal reason and return no menu kind.
esc_stick_kind_t	esc_stick_kind (const esc_profile_t p, const char *why)
	Which menu the engine runs for `p`, or ESC_STICK_KIND_NONE with the reason in `why` (a static string; may be NULL).
uint32_t	esc_stick_profile_mv (const esc_profile_t *p)
	The supply voltage a profile asks for, mV: the lowest stated cell count among its models at 3800mV a LiPo cell or 1200mV a NiMH cell, which is above that model's cut-off and under every model's maximum. 0 when no model states a cell count.
uint32_t	esc_stick_model_mv (const esc_profile_t *p, int model)
	The supply voltage for model `model` of `p`, mV: its own lowest cell count at the rates above, where it states one; else, and for -1, the family's (esc_stick_profile_mv()).
uint32_t	esc_stick_model_v_max (const esc_profile_t *p, int model)
	The highest supply voltage model `model` of `p` is rated for, mV: its v_max_mv.
uint32_t	esc_stick_model_ma_max (const esc_profile_t *p, int model)
	The continuous current model `model` of `p` is rated for, mA: its current_a.
uint32_t	esc_stick_model_v_min (const esc_profile_t *p, int model)
	The lowest input model `model` of `p` takes, mV: its v_min_mv.
esc_stick_rating_t	esc_stick_rating (const esc_profile_t *p, int model, uint32_t mv, uint32_t ma, bool by_hand)
	Whether `mv` and `ma` suit model `model` of `p` (-1: every model of the family).
bool	esc_stick_rating_unknown (const esc_profile_t *p, int model, uint32_t mv, bool by_hand)
	Whether the data cannot vouch for `mv` on model `model:` the rated voltage is not stated, and the voltage is set by hand (`by_hand`) or is not the model's own cell count's – the family's lowest standing in for a model that states none, or none at all.
bool	esc_stick_is_action (const esc_item_t *it)
	Whether `it` is an action rather than a setting: keyed reset or exit.
const char *	esc_stick_not_offered (const esc_item_t *it)
	Why `it` is not offered as a change, or NULL when it is: an action, or an item with a single value, which is either the only setting there is or a rule written as a value ("N beeps = N cells") – nothing to choose either way, and nothing the menu would sound in order.
esc_throttle_t	esc_stick_change_entry (const esc_profile_t p, const esc_stick_change_t c)
	The stick position change `c` is powered up from: its value's entry_throttle where the manual names one, else the profile's entry.
static bool	hand_powered (const esc_profile_t *p)
	Whether the profile asks for a hand at a powered ESC.
static const char *	entry_refused (const esc_profile_t p, const esc_stick_change_t ch, size_t i, const esc_stick_timing_t *t)
	Why change `i` cannot be powered up from its own entry position, or NULL.
bool	esc_stick_no (const char *why, const char text)
	Set *`why` to `text` when `why` is not NULL, and return false.
bool	esc_stick_check (const esc_profile_t p, const esc_stick_change_t ch, size_t n, const esc_stick_timing_t t, const char *why)
	Whether a run of `n` changes under `t` can start on `p`; the reason in `why` when not.

Detailed Description

Stick programming: what can run.

Which profiles the engine runs, the voltage and current set points a model is given, and the check a run's changes and timing pass before it starts. See esc_stick.h.

SPDX-License-Identifier: MIT

Function Documentation

◆ entry_refused()

const char * entry_refused	(	const esc_profile_t *	p,
		const esc_stick_change_t *	ch,
		size_t	i,
		const esc_stick_timing_t *	t )

static

Why change i cannot be powered up from its own entry position, or NULL.

The run powers each change up from the position its value is programmed from (esc_stick_change_entry()): a Kontronik car mode from the middle, the neutral the mode teaches. The profile-wide rules of esc_stick_kind() hold for that position as they hold for the profile's:

A power-up takes one position. A two-stage menu, or one that takes several changes a power-up, makes its changes in the order the ESC sounds them, not the order asked, so every change of the run shares the first one's position; a mix is refused, not reordered. A one-stage menu takes one change a power-up and powers each up from its own.
The rest is that position where the profile names none, and the select move has to differ from it.
A power-up's entry time is what the run waits (esc_stick_change_entry_ms()): its value's entry_hold_ms where the manual gives one, else the timing's entry, and no less than the longest at_power_up hold; the changes a power-up shares share one. A move to a named rest needs a time the profile, the value or an at_power_up step's hold states.
A hand at a powered ESC with the stick at MAX is not asked for. MID is, where the value names it: the manual's motor-off in the middle.

Parameters

p	The profile.
ch	The changes of the run.
i	Index of the change checked.
t	The timing.

Returns: A static reason string, or NULL when the change can be powered up.

◆ esc_stick_change_entry()

esc_throttle_t esc_stick_change_entry	(	const esc_profile_t *	p,
		const esc_stick_change_t *	c )

The stick position change c is powered up from: its value's entry_throttle where the manual names one, else the profile's entry.

A run moves the stick there with the supply off and seen off, holds it ESC_STICK_SIGNAL_MS, and only then switches the supply on.

Parameters

p	The profile.
c	The change.

Returns: The throttle position at power-up.

◆ esc_stick_check()

bool esc_stick_check	(	const esc_profile_t *	p,
		const esc_stick_change_t *	ch,
		size_t	n,
		const esc_stick_timing_t *	t,
		const char **	why )

Whether a run of n changes under t can start on p; the reason in why when not.

Refused, never adjusted: a timing that cannot fit the profile's select window is a setting to change, not one to guess.

Parameters

p	The profile.
ch	The changes, in order.
n	Number of changes in `ch`.
t	The timing.
why	Receives the reason when refused, or NULL.

Returns: true when the run can start.

◆ esc_stick_is_action()

bool esc_stick_is_action ( const esc_item_t * it )

Whether it is an action rather than a setting: keyed reset or exit.

Selecting one makes the ESC act on the select move; it sounds no values, and the engine does not offer it.

Parameters

it	The menu item.

Returns: true when the item is an action.

◆ esc_stick_kind()

esc_stick_kind_t esc_stick_kind	(	const esc_profile_t *	p,
		const char **	why )

Which menu the engine runs for p, or ESC_STICK_KIND_NONE with the reason in why (a static string; may be NULL).

An assisted profile runs only through its manual steps (esc_profile_t's manual), and only when each can be waited for: no step during the menu, whose moment the run cannot know, and a hand at a powered ESC – an at_power_up or before_menu step – only with the stick at MIN for the entry. Otherwise the reason is "manual step".

Parameters

p	The profile.
why	Receives the reason when the engine cannot run it, or NULL.

Returns: The menu kind, or ESC_STICK_KIND_NONE.

◆ esc_stick_listen()

esc_throttle_t esc_stick_listen ( const esc_profile_t * p )

Where the stick rests while the menu sounds: the profile's listen move, else where the entry left it.

Parameters

p	The profile.

Returns: The throttle position to hold.

◆ esc_stick_model_ma_max()

uint32_t esc_stick_model_ma_max	(	const esc_profile_t *	p,
		int	model )

The continuous current model model of p is rated for, mA: its current_a.

For -1, the lowest stated among its models. 0 where none is stated.

Parameters

p	The profile.
model	Index into the models, or -1 for the family.

Returns: The rated current, mA, or 0 when not stated.

◆ esc_stick_model_mv()

uint32_t esc_stick_model_mv	(	const esc_profile_t *	p,
		int	model )

The supply voltage for model model of p, mV: its own lowest cell count at the rates above, where it states one; else, and for -1, the family's (esc_stick_profile_mv()).

Parameters

p	The profile.
model	Index into the models, or -1 for the family.

Returns: The supply voltage, mV.

◆ esc_stick_model_v_max()

uint32_t esc_stick_model_v_max	(	const esc_profile_t *	p,
		int	model )

The highest supply voltage model model of p is rated for, mV: its v_max_mv.

For -1, the lowest of every model's, the one every model takes. 0 where the data does not state it – for -1, where a model does not, or there is none.

Parameters

p	The profile.
model	Index into the models, or -1 for the family.

Returns: The rated voltage, mV, or 0 when not stated.

◆ esc_stick_model_v_min()

uint32_t esc_stick_model_v_min	(	const esc_profile_t *	p,
		int	model )

The lowest input model model of p takes, mV: its v_min_mv.

For -1, the highest stated among its models. 0 where none is stated.

Parameters

p	The profile.
model	Index into the models, or -1 for the family.

Returns: The lowest input voltage, mV, or 0 when not stated.

◆ esc_stick_no()

bool esc_stick_no	(	const char **	why,
		const char *	text )

Set *why to text when why is not NULL, and return false.

In esc_stick_rules.c.

Parameters

why	Receives the reason, or NULL to set nothing.
text	The reason.

Returns: false, always.

◆ esc_stick_not_offered()

const char * esc_stick_not_offered ( const esc_item_t * it )

Why it is not offered as a change, or NULL when it is: an action, or an item with a single value, which is either the only setting there is or a rule written as a value ("N beeps = N cells") – nothing to choose either way, and nothing the menu would sound in order.

Parameters

it	The menu item.

Returns: A static reason string, or NULL when the item is offered.

◆ esc_stick_pct()

float esc_stick_pct ( esc_throttle_t pos )

A throttle position as the output's percentage.

Parameters

pos	The throttle position.

Returns: The output percentage of pos.

◆ esc_stick_profile_mv()

uint32_t esc_stick_profile_mv ( const esc_profile_t * p )

The supply voltage a profile asks for, mV: the lowest stated cell count among its models at 3800mV a LiPo cell or 1200mV a NiMH cell, which is above that model's cut-off and under every model's maximum. 0 when no model states a cell count.

Parameters

p	The profile.

Returns: The supply voltage, mV, or 0 when no model states a cell count.

◆ esc_stick_rating()

esc_stick_rating_t esc_stick_rating	(	const esc_profile_t *	p,
		int	model,
		uint32_t	mv,
		uint32_t	ma,
		bool	by_hand )

Whether mv and ma suit model model of p (-1: every model of the family).

A voltage over the rated one (esc_stick_model_v_max()) is refused, set by hand (by_hand) or taken from the cell count, and so is one under the lowest input the model states (v_min_mv; for -1 the highest of its models'). A current over the rated one, where stated, is refused. A rating the data does not state refuses nothing: esc_stick_rating_unknown() says when the operator is to be told.

Parameters

p	The profile.
model	Index into the models, or -1 for the family.
mv	Supply voltage, mV.
ma	Supply current limit, mA.
by_hand	Whether the voltage was set by hand.

Returns: The rating that the set points break, or ESC_STICK_RATING_OK.

◆ esc_stick_rating_unknown()

bool esc_stick_rating_unknown	(	const esc_profile_t *	p,
		int	model,
		uint32_t	mv,
		bool	by_hand )

Whether the data cannot vouch for mv on model model: the rated voltage is not stated, and the voltage is set by hand (by_hand) or is not the model's own cell count's – the family's lowest standing in for a model that states none, or none at all.

The run goes ahead; the screen says the ESC's rating is unknown.

Parameters

p	The profile.
model	Index into the models, or -1 for the family.
mv	Supply voltage, mV.
by_hand	Whether the voltage was set by hand.

Returns: true when the rating is unknown.

◆ hand_fits()

bool hand_fits ( const esc_profile_t * p )

static

Whether every manual step can be waited for.

A step during the menu has no moment the run can know. A hand at a powered ESC – held while the supply comes on, or after the entry – is asked for with the stick where the entry put it, so only for an entry at MIN, the motor-off position: a person is not asked to reach for a powered ESC whose stick is at MID or MAX. A step before the supply goes off asks for no hand at all – the operator watches the ESC – so any stick position holds it.

Parameters

p	The profile.

Returns: true when every manual step can be waited for.

◆ hand_powered()

bool hand_powered ( const esc_profile_t * p )

static

Whether the profile asks for a hand at a powered ESC.

Parameters

p	The profile.

Returns: true when an at_power_up or before_menu step is due.

◆ menu_start()

const esc_manual_t * menu_start ( const esc_profile_t * p )

static

The step that starts the menu, or NULL.

Parameters

p	The profile.

Returns: The step marked starts_menu, or NULL when none is.

◆ refuse()

esc_stick_kind_t refuse	(	const char **	why,
		const char *	text )

static

Set the refusal reason and return no menu kind.

Parameters

why	Receives `text` when not NULL.
text	The static reason string.

Returns: ESC_STICK_KIND_NONE.

◆ value_holds()

bool value_holds ( const esc_profile_t * p )

static

Whether a value states its own entry time: the profile-wide rest rule leaves such a profile to the per-change one (entry_refused()), which sees the value's time.

Parameters

p	The profile.

Returns: true when a value has an entry_hold_ms.

◆ values_repeat()

bool values_repeat ( const esc_profile_t * p )

static

Whether any value number appears in two items.

Parameters

p	The profile.

Returns: true when a value number repeats across items.

Functions

Detailed Description

Function Documentation

◆ entry_refused()

◆ esc_stick_change_entry()

◆ esc_stick_check()

◆ esc_stick_is_action()

◆ esc_stick_kind()

◆ esc_stick_listen()

◆ esc_stick_model_ma_max()

◆ esc_stick_model_mv()

◆ esc_stick_model_v_max()

◆ esc_stick_model_v_min()

◆ esc_stick_no()

◆ esc_stick_not_offered()

◆ esc_stick_pct()

◆ esc_stick_profile_mv()

◆ esc_stick_rating()

◆ esc_stick_rating_unknown()

◆ hand_fits()

◆ hand_powered()

◆ menu_start()

◆ refuse()

◆ value_holds()

◆ values_repeat()