openyge.h

Go to the documentation of this file.

 
#ifndef RCBENCH_OPENYGE_H
#define RCBENCH_OPENYGE_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ------------------------------------------------------------- the wire */
 
#define OPENYGE_SYNC            0xA5u   
#define OPENYGE_VERSION         3u      
 
#define OPENYGE_HDR_V3          6u      
#define OPENYGE_HDR_LEGACY      4u      
#define OPENYGE_CRC_BYTES       2u      
 
#define OPENYGE_TELEMETRY_BYTES 26u     
#define OPENYGE_CONTROL_BYTES   4u      

#define OPENYGE_MIN_FRAME       (OPENYGE_HDR_LEGACY + OPENYGE_CRC_BYTES)
#define OPENYGE_MAX_FRAME       140u    

#define OPENYGE_CRC_INIT        0x0000u
#define OPENYGE_CRC_CHECK       0x31C3u

uint16_t openyge_crc(uint16_t crc, const void *data, size_t len);

#define OPENYGE_DEV_MASTER      0x80u
#define OPENYGE_DEV_ADDR_MASK   0x7Fu
#define OPENYGE_DEV_BROADCAST   0x00u

#define OPENYGE_TEMP_OFFSET     40

typedef enum {
    OPENYGE_FT_TELE_AUTO        = 0x00, 
    OPENYGE_FT_TELE_RESP        = 0x02, 
    OPENYGE_FT_TELE_REQ         = 0x03, 
    OPENYGE_FT_WRITE_PARAM_RESP = 0x04, 
    OPENYGE_FT_WRITE_PARAM_REQ  = 0x05, 
} openyge_frame_type_t;
 
/* ------------------------------------------------------------ decoding */
 
typedef struct {
    uint8_t version;  
    uint8_t type;     
    uint8_t seq;      
    uint8_t device;   
    bool    legacy;   
} openyge_header_t;

typedef struct {
    openyge_header_t hdr;
    uint8_t payload[OPENYGE_MAX_FRAME];  
    uint8_t payload_len;                 
} openyge_frame_t;

typedef struct {
    uint8_t  buf[OPENYGE_MAX_FRAME];
    uint8_t  len;
    /* Counters for the analyser screen: a quiet line, a noisy one and a
     * wrong baud rate are distinguished here.  crc_errors and rejected count
     * a failing sync candidate once, when it reaches the front of the
     * buffer; bytes dropped ahead of a candidate count under resyncs. */
    uint32_t frames;
    uint32_t crc_errors;
    uint32_t resyncs;
    uint32_t rejected;   
} openyge_decoder_t;

void openyge_decoder_reset(openyge_decoder_t *d);

bool openyge_decode_byte(openyge_decoder_t *d, uint8_t byte,
                         openyge_frame_t *out);
 
/* ------------------------------------------------------------ telemetry */
 
typedef struct {
    float    volts;          
    float    amps;           
    uint16_t consumption_mah; 
    uint32_t erpm;           
    int8_t   pwm_pct;        
    int8_t   throttle_pct;   
    float    bec_volts;      
    float    bec_amps;       
    int16_t  temp_c;         
    int16_t  bec_temp_c;     
    int16_t  cap_temp_c;     
    int16_t  aux_temp_c;     
    uint8_t  status1;        
    uint8_t  status2;        
    uint16_t pidx;           
    uint16_t pdata;          
} openyge_telemetry_t;

bool openyge_frame_has_telemetry(const openyge_frame_t *f);

bool openyge_telemetry_parse(const openyge_frame_t *f,
                             openyge_telemetry_t *out);

bool openyge_control_parse(const openyge_frame_t *f, uint16_t *index,
                           uint16_t *param);
 
/* ------------------------------------------------------------- encoding */

size_t openyge_encode(uint8_t *out, size_t cap, uint8_t type, uint8_t device,
                      uint8_t seq, const void *payload, size_t payload_len);

size_t openyge_build_telemetry_request(uint8_t *out, size_t cap,
                                       uint8_t device, uint8_t seq);

size_t openyge_build_param_write(uint8_t *out, size_t cap, uint8_t device,
                                 uint8_t seq, uint16_t index, uint16_t value);
 
/* ---------------------------------------------------------------- status */

typedef enum {
    OPENYGE_SUBJECT_ESC = 0,
    OPENYGE_SUBJECT_BEC,
} openyge_subject_t;

typedef enum {
    OPENYGE_ST_DISARMED          = 0x0,
    OPENYGE_ST_POWER_CUT         = 0x1,
    OPENYGE_ST_FAST_START        = 0x2,
    OPENYGE_ST_ALIGN_FOR_POS     = 0x4,
    OPENYGE_ST_BRAKING_NORM_FINI = 0x6,
    OPENYGE_ST_BRAKING_SYNC_FINI = 0x7,
    OPENYGE_ST_STARTING          = 0x8,
    OPENYGE_ST_BRAKING_NORM      = 0x9,
    OPENYGE_ST_BRAKING_SYNC      = 0xA,
    OPENYGE_ST_WINDMILLING       = 0xC,
    OPENYGE_ST_RUNNING_NORM      = 0xE,
} openyge_state_t;

typedef struct {
    uint8_t state;              
    bool    state_known;        
 
    /*
     * The overloaded combination.  0x80|0x40 would read as a BEC (battery
     * eliminator circuit) over-current, which cannot occur, so that exact
     * value means the ESC reports a dirty input signal instead.  While this
     * is set, the subject and the warning flags below carry no meaning.
     */
    bool    setpoint_noise;
 
    openyge_subject_t subject;  
    bool    warn_undervoltage;
    bool    warn_overtemp;
    bool    warn_overcurrent;
 
    /*
     * A warning bit alone is a caution; it is a fault only in combination
     * with the state.  Over-voltage has no bit of its own: it is the absence
     * of warnings while the power is cut.  A decoder that reports flags
     * without the state misses that condition.
     */
    bool    fault_overvoltage;
    bool    fault_undervoltage;
    bool    fault_overtemp;
    bool    fault_overcurrent;
    bool    any_fault;
} openyge_status_t;

void openyge_status_decode(uint8_t status1, openyge_status_t *out);

const char *openyge_state_name(uint8_t state);
 
/* ------------------------------------------------------------ parameters */

#define OPENYGE_MAX_PARAMS 64

#define OPENYGE_P_COUNT        0
#define OPENYGE_P_MOTOR_POLES  20
#define OPENYGE_P_PINION_TEETH 21
#define OPENYGE_P_MAIN_TEETH   22
 
typedef struct {
    uint16_t value[OPENYGE_MAX_PARAMS];  
    uint64_t seen;            
    /* Parameter 0.  Zero means the count has not arrived: a table of zero
     * parameters cannot exist, so no separate flag is needed. */
    uint16_t count;
    bool     writes_pending;  
} openyge_params_t;

void openyge_params_reset(openyge_params_t *p);

void openyge_params_observe(openyge_params_t *p, uint16_t index,
                            uint16_t value);

void openyge_params_begin_writes(openyge_params_t *p);
void openyge_params_end_writes(openyge_params_t *p);

bool openyge_params_complete(const openyge_params_t *p);

bool openyge_params_get(const openyge_params_t *p, uint16_t index,
                        uint16_t *out);

float openyge_params_progress(const openyge_params_t *p);

bool openyge_motor_rpm(const openyge_params_t *p, uint32_t erpm,
                       float *motor_rpm);
bool openyge_head_rpm(const openyge_params_t *p, uint32_t erpm,
                      float *head_rpm);
 
#ifdef __cplusplus
}
#endif
 
#endif /* RCBENCH_OPENYGE_H */