8.1.6. How to Implement an Analog Front-End Driver

This section gives a guideline how add a new AFE to the project.

8.1.6.1. The Example

The AFE is from the manufacturer called Super BMS ICs (SB-IC) and the the IC is named Vulpes G 2000 (VG2000) from the IC family VG.

8.1.6.2. Basic Directory Structure

  1. Adapt tools/waf-tools/bms_config_validator.py to recognize the new manufacturer and the IC.

  2. Add the SB-IC manufacturer directory sb-ic: src/app/driver/afe/sb-ic.

  3. Add the API directory api for SB-IC manufacturer: src/app/driver/afe/sb-ic/api.

  4. Add the IC vg2 directory: src/app/driver/afe/sb-ic/vg2000.

  5. Add the api directory: src/app/driver/afe/sb-ic/vg2000/api.

  6. Add the config directory: src/app/driver/afe/sb-ic/vg2000/config.

  7. If there is special code code from the IC vendor for that IC: Add the vendor directory src/app/driver/afe/sb-ic/vg2000/vendor. The vendor code should be placed here verbatim without any changes to the source code or to the source code organization.

  8. If there is shared code between all ICs or family of ICs from that manufacturer, add the common directory: src/app/driver/afe/sb-ic/common.

  9. If there is common shared code from the IC vendor: Add the vendor directory src/app/driver/afe/sb-ic/common/vendor. The vendor code should be placed here verbatim without any changes to the source code or to the source code organization.

  10. If there needs to be common shared code developed for the family: Add the vg directory src/app/driver/afe/sb-ic/common/vg.

After that the directories are setup correctly.

Example: If there is

  • common code from the vendor,

  • common code for the family from the vendor,

  • special code for the IC from the vendor,

  • common code developed,

  • common code for the family developed and

  • special code for the IC developed

then the directory structure is as follows:

src
└── app
    └── src
        └── driver
            └── afe
                └── sb-ic
                    ├── api
                    ├── common
                    │   ├── vendor  # vendor: common shared vendor code without modification
                    │   ├── vg      # developed: family common shared code
                    │   └── .       # developed: manufacturer common shared code
                    └── vg2000
                        ├── api     # api files go here
                        ├── config  # configuration files go here
                        ├── vendor  # vendor: special code for the IC vendor goes here
                        └── .       # developed: driver code developed

8.1.6.3. Required Files

The files listed here are the required minimum to keep the different manufacturer driver consistent.

8.1.6.3.1. Driver

  • sb-ic_vg2000.c

  • sb-ic_vg2000.h

  • sb-ic_vg2000.json

  • wscript

  • Additional files MAY be added as needed.

8.1.6.3.2. API Files

  • api/sb-ic_vg2000_afe.h

  • api/sb-ic_vg2000_afe.c

  • api/sb-ic_vg2000_afe_dma.c

  • api/sb-ic_vg2000_afe_dma.h

  • There SHOULD be no additional files.

8.1.6.3.3. Configuration Files

  • sb-ic_vg2000_cfg.c

  • sb-ic_vg2000_cfg.h

  • sb-ic_vg2000_afe_dma_cfg.c

  • sb-ic_vg2000_afe_dma_cfg.h

  • There SHOULD be no additional files.

The file structure should look like this (for the sake of simplicity no common shared code and no vendor code):

src
└── app
    └── src
        └── driver
            └── afe
                └── sb-ic
                    └── vg2000
                        ├── api
                        │   ├──sb-ic_vg2000_afe.h
                        │   ├──sb-ic_vg2000_afe.c
                        │   ├──sb-ic_vg2000_afe_dma.c
                        │   └──sb-ic_vg2000_afe_dma.h
                        ├── config
                        │   ├──sb-ic_vg2000_cfg.c
                        │   ├──sb-ic_vg2000_cfg.h
                        │   ├──sb-ic_vg2000_afe_dma_cfg.c
                        │   └──sb-ic_vg2000_afe_dma_cfg.h
                        ├── sb-ic_vg2000.c
                        ├── sb-ic_vg2000.h
                        ├── sb-ic_vg2000.json
                        └── wscript

8.1.6.4. Additional implementations

To ensure the IC’s name is written correctly to the ver_foxbmsBuildConfiguration struct, a short name has to be added to the VER_AFE_e enum in the app_build_cfg.h header.

Furthermore, the get_afe_name function in create_app_build_cfg and its helper functions (there is one for each manufacturer) have to be updated or added, so the new IC’s short name can be retrieved from its complete name in bms.json.

Last but not least the sensor short name has to be added to the f_Afes enum in the foxbms.sym file.

The enum’s values must be equal to the one in app_build_cfg.h, so the build configuration can be read out using CAN.