libelec.h

Go to the documentation of this file.

/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/*
 * Copyright 2023 Saso Kiselkov. All rights reserved.
 */
#ifndef _LIBELEC_H_
#define _LIBELEC_H_
 
#include <stdarg.h>
#include <stdbool.h>
 
#include <acfutils/conf.h>
#include <acfutils/geom.h>
#include <acfutils/sysmacros.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if !defined(STATIC_ARRAY_LEN_ARG) && !defined(CONST_ARRAY_LEN_ARG)
#if __STDC_VERSION__ >= 199901L && !defined(_MSC_VER)
#define STATIC_ARRAY_LEN_ARG(len)   static len
#define CONST_ARRAY_LEN_ARG(len)    static len
#else   /* __STDC_VERSION__ < 199901L || defined(_MSC_VER) */
#define STATIC_ARRAY_LEN_ARG(len)
#define CONST_ARRAY_LEN_ARG(len)    len
#endif  /* __STDC_VERSION__ < 199901L || defined(_MSC_VER) */
#endif  /* !defined(STATIC_ARRAY_LEN_ARG) && !defined(CONST_ARRAY_LEN_ARG) */
 
enum {
    ELEC_MAX_SRCS = 64
};
 
typedef struct elec_sys_s elec_sys_t;
typedef struct elec_comp_s elec_comp_t;
typedef struct elec_comp_info_s elec_comp_info_t;
 
typedef enum {
    ELEC_BATT,
    ELEC_GEN,
    ELEC_TRU,
    ELEC_INV,
    ELEC_XFRMR,
    ELEC_LOAD,
    ELEC_BUS,
    ELEC_CB,
    ELEC_SHUNT,
    ELEC_TIE,
    ELEC_DIODE,
    ELEC_LABEL_BOX
} elec_comp_type_t;
 
typedef double (*elec_get_temp_cb_t)(elec_comp_t *comp, void *userinfo);
typedef struct {
    double  volts;      
    double  capacity;   
    double  max_pwr;    
    double  chg_R;      
    elec_get_temp_cb_t get_temp;
} elec_batt_info_t;
 
typedef double (*elec_get_rpm_cb_t)(elec_comp_t *comp, void *userinfo);
typedef struct elec_gen_info_s {
    double  volts;      
    double  freq;       
    double  stab_rate_U;    
    double  stab_rate_f;    
    double  exc_rpm;    
    double  min_rpm;    
    double  max_rpm;    
    vect2_t *eff_curve; 
    elec_get_rpm_cb_t get_rpm;
} elec_gen_info_t;
 
typedef struct {
    double      in_volts;   
    double      min_volts;  
    double      out_volts;  
    double      out_freq;   
    vect2_t     *eff_curve; 
    const elec_comp_info_t *ac; 
    const elec_comp_info_t *dc; 
    bool        charger;
    const elec_comp_info_t *batt;
    const elec_comp_info_t *batt_conn;
    double      curr_lim;   
} elec_tru_info_t;
 
typedef struct {
    double      in_volts;   
    double      out_volts;  
    vect2_t     *eff_curve; 
    const elec_comp_info_t *input;  
    const elec_comp_info_t *output; 
} elec_xfrmr_info_t;
 
typedef double (*elec_get_load_cb_t)(elec_comp_t *comp, void *userinfo);
typedef struct {
    bool        ac;
    bool        stab;
    double      incap_C;
    double      incap_R;
    double      incap_leak_Qps;
    double      min_volts;
    elec_get_load_cb_t get_load;
    double      std_load;
} elec_load_info_t;
 
typedef struct {
    bool            ac;     
    const elec_comp_info_t  **comps;    
    size_t          n_comps;    
} elec_bus_info_t;
 
typedef struct {
    double          max_amps;   
    double          rate;       
    bool            fuse;       
    bool            triphase;   
} elec_cb_info_t;
 
typedef struct {
    const elec_comp_info_t  *sides[2];
} elec_diode_info_t;
 
typedef enum {
    GUI_LOAD_GENERIC,
    GUI_LOAD_MOTOR
} gui_load_type_t;
 
typedef struct {
    vect2_t         pos;
    vect2_t         sz;
    double          font_scale;
} elec_label_box_info_t;
 
struct elec_comp_info_s {
    elec_comp_type_t        type;   
    char                *name;  
    void                *userinfo;
    bool                autogen;
    char                location[32];
    double              int_R;
    unsigned            parse_linenum;
    union {
        elec_batt_info_t    batt;   
        elec_gen_info_t     gen;    
        elec_tru_info_t     tru;
        elec_xfrmr_info_t   xfrmr;
        elec_load_info_t    load;   
        elec_bus_info_t     bus;    
        elec_cb_info_t      cb; 
        elec_diode_info_t   diode;  
        elec_label_box_info_t   label_box;
    };
    struct {
        vect2_t         pos;
        double          sz;
        int         rot;
        gui_load_type_t     load_type;
        bool            virt;
        bool            invis;
        vect3_t         color;
    } gui;
};
 
typedef void (*elec_user_cb_t)(elec_sys_t *sys, bool pre, void *userinfo);
 
elec_sys_t *libelec_new(const char *filename);
void libelec_destroy(elec_sys_t *sys);
 
const elec_comp_info_t *libelec_get_comp_infos(const elec_sys_t *sys,
    size_t *num_infos);
 
bool libelec_sys_start(elec_sys_t *sys);
void libelec_sys_stop(elec_sys_t *sys);
bool libelec_sys_is_started(const elec_sys_t *sys);
bool libelec_sys_can_start(const elec_sys_t *sys);
 
void libelec_sys_set_time_factor(elec_sys_t *sys, double time_factor);
double libelec_sys_get_time_factor(const elec_sys_t *sys);
 
void libelec_serialize(elec_sys_t *sys, conf_t *ser, const char *prefix);
bool libelec_deserialize(elec_sys_t *sys, const conf_t *ser,
    const char *prefix);
 
#ifdef  LIBELEC_WITH_NETLINK
void libelec_enable_net_send(elec_sys_t *sys);
void libelec_disable_net_send(elec_sys_t *sys);
void libelec_enable_net_recv(elec_sys_t *sys);
void libelec_disable_net_recv(elec_sys_t *sys);
#endif  /* defined(LIBELEC_WITH_NETLINK) */
 
#ifdef  LIBELEC_WITH_LIBSWITCH
void libelec_create_cb_switches(const elec_sys_t *sys, const char *prefix,
    float anim_rate);
#endif  /* defined(LIBELEC_WITH_LIBSWITCH) */
 
#ifdef  LIBELEC_SLOW_DEBUG
void libelec_step(elec_sys_t *sys);
#endif
 
/* User callbacks */
void libelec_add_user_cb(elec_sys_t *sys, bool pre, elec_user_cb_t cb,
    void *userinfo);
void libelec_remove_user_cb(elec_sys_t *sys, bool pre, elec_user_cb_t cb,
    void *userinfo);
 
/* Finding devices and interrogating their configuration */
elec_comp_t *libelec_comp_find(elec_sys_t *sys, const char *name);
void libelec_walk_comps(const elec_sys_t *sys,
    void (*cb)(elec_comp_t *, void *), void *userinfo);
const elec_comp_info_t *libelec_comp2info(const elec_comp_t *comp);
 
bool libelec_comp_is_AC(const elec_comp_t *comp);
elec_comp_type_t libelec_comp_get_type(const elec_comp_t *comp);
const char *libelec_comp_get_name(const elec_comp_t *comp);
const char *libelec_comp_get_location(const elec_comp_t *comp);
bool libelec_comp_get_autogen(const elec_comp_t *comp);
 
size_t libelec_comp_get_num_conns(const elec_comp_t *comp);
elec_comp_t *libelec_comp_get_conn(const elec_comp_t *comp, size_t i);
 
/* Electrical state querying */
double libelec_comp_get_in_volts(const elec_comp_t *comp);
double libelec_comp_get_out_volts(const elec_comp_t *comp);
double libelec_comp_get_in_amps(const elec_comp_t *comp);
double libelec_comp_get_out_amps(const elec_comp_t *comp);
double libelec_comp_get_in_pwr(const elec_comp_t *comp);
double libelec_comp_get_out_pwr(const elec_comp_t *comp);
double libelec_comp_get_in_freq(const elec_comp_t *comp);
double libelec_comp_get_out_freq(const elec_comp_t *comp);
double libelec_comp_get_incap_volts(const elec_comp_t *comp);
bool libelec_comp_is_powered(const elec_comp_t *comp);
double libelec_comp_get_eff(const elec_comp_t *gen);
unsigned libelec_comp_get_srcs(const elec_comp_t *comp,
    elec_comp_t *srcs[CONST_ARRAY_LEN_ARG(ELEC_MAX_SRCS)]);
 
/* Failures */
void libelec_comp_set_failed(elec_comp_t *comp, bool failed);
bool libelec_comp_get_failed(const elec_comp_t *comp);
void libelec_comp_set_shorted(elec_comp_t *comp, bool shorted);
bool libelec_comp_get_shorted(const elec_comp_t *comp);
double libelec_gen_set_random_volts(elec_comp_t *comp, double stddev);
double libelec_gen_set_random_freq(elec_comp_t *comp, double stddev);
 
/* Callback setup */
void libelec_comp_set_userinfo(elec_comp_t *comp, void *userinfo);
void *libelec_comp_get_userinfo(const elec_comp_t *comp);
 
void libelec_batt_set_temp_cb(elec_comp_t *batt, elec_get_temp_cb_t cb);
elec_get_temp_cb_t libelec_batt_get_temp_cb(const elec_comp_t *batt);
 
void libelec_gen_set_rpm_cb(elec_comp_t *gen, elec_get_rpm_cb_t cb);
elec_get_rpm_cb_t libelec_gen_get_rpm_cb(const elec_comp_t *gen);
 
void libelec_load_set_load_cb(elec_comp_t *load, elec_get_load_cb_t cb);
elec_get_load_cb_t libelec_load_get_load_cb(elec_comp_t *load);
 
/* Circuit breakers */
void libelec_cb_set(elec_comp_t *comp, bool set);
bool libelec_cb_get(const elec_comp_t *comp);
double libelec_cb_get_temp(const elec_comp_t *comp);
 
/* Ties */
void libelec_tie_set_list(elec_comp_t *comp, size_t list_len,
    elec_comp_t *const bus_list[STATIC_ARRAY_LEN_ARG(list_len)]);
void libelec_tie_set(elec_comp_t *comp, ...) SENTINEL_ATTR;
void libelec_tie_set_v(elec_comp_t *comp, va_list ap);
void libelec_tie_set_all(elec_comp_t *comp, bool tied);
bool libelec_tie_get_all(elec_comp_t *comp);
size_t libelec_tie_get_list(elec_comp_t *comp, size_t cap,
    elec_comp_t *bus_list[STATIC_ARRAY_LEN_ARG(cap)]);
size_t libelec_tie_get_num_buses(const elec_comp_t *comp);
/*
 * Due to default argument promotion and va_start underneath,
 * we cannot use the native bool type here.
 */
bool libelec_tie_get(elec_comp_t *tie, bool_t exhaustive, ...)
    SENTINEL_ATTR;
bool libelec_tie_get_v(elec_comp_t *tie, bool exhaustive, va_list ap);
 
/*
 * Generators
 */
void libelec_gen_set_rpm(elec_comp_t *gen, double rpm);
double libelec_gen_get_rpm(const elec_comp_t *gen);
 
/* Batteries */
double libelec_batt_get_chg_rel(const elec_comp_t *batt);
void libelec_batt_set_chg_rel(elec_comp_t *batt, double chg_rel);
double libelec_batt_get_temp(const elec_comp_t *batt);
void libelec_batt_set_temp(elec_comp_t *batt, double T);
 
/* Miscellaneous */
bool libelec_chgr_get_working(const elec_comp_t *chgr);
 
double libelec_phys_get_batt_voltage(double U_nominal, double chg_rel,
    double I_rel);
 
#ifdef __cplusplus
}
#endif
 
#endif  /* _LIBELEC_H_ */