Easy-to-use, low-cost, open-source solution that includes compatible hardware and software sets of tools. This comprehensive solution is designed to fulfill the need for firmware energy profiling, as well as State of Charge (SoC) and State of Health (SoH) algorithm evaluation for real LiPo battery-powered embedded devices.

Official YouTube channel

---

Content

• Features
• Using OpenEPT Utilities
• Contributor guide
• Documentation
• Acknowledgments

---

Features

The OpenEPT Utilities repository contains host-side tools used to generate, extract, and manage configuration and memory images for OpenEPT devices. The utilities provide a common mechanism for preparing device-specific system parameters while supporting the different memory organizations used by individual OpenEPT boards.

Main features include:

• Generation of binary System images from human-readable parameter files
• Extraction of System parameters from existing binary images
• Configurable System image size for different OpenEPT devices
• Automatic hardware serial-number generation
• Persistent serial-number registry
• Automatic or explicitly selected device numbering
• Independent device-number sequences for different OpenEPT device types
• Reuse of previously assigned serial numbers when regenerating an image for an existing device
• Automatic MAC-address generation where required
• LittleFS filesystem image generation
• LittleFS filesystem extraction
• Generation of complete Energy Profiler Probe memory images
• Extraction of complete Energy Profiler Probe memory images
• CRC32 protection of System parameter data
• Support for device-specific image-generation metadata

The configuration utilities are located under:

config/
├── examples/
│   ├── charger/
│   └── epp/
├── filesystem/
│   ├── extract.py
│   └── gen.py
├── image/
│   ├── extract.py
│   └── gen.py
└── system/
    ├── extract.py
    ├── gen.py
    └── serials/

The utilities are organized into three main groups.

System Image Utilities

The config/system directory contains utilities for generating and extracting the System region used to store device-specific parameters. System parameters are provided through a human-readable systemParams.txt file. In addition to firmware parameters, the file can contain metadata used only during image generation.

An example configuration is:

@DEVICE_TYPE:CHR
@SERIAL_EXTRA_DATA:1000000
@SYSTEM_SIZE:128

HW_SER:<gen>
FW_VER:1.0.0
CH_CURR:100
TERM_VOLT:4.2
TERM_CUR:3
MAX_CUR:5

Entries beginning with @ are generation metadata and are not stored as firmware parameters in the generated System image. The @SYSTEM_SIZE field specifies the size of the generated System region, allowing the same utility to be used for devices with different non-volatile memory configurations. The generated System image contains a header, serialized parameter data, CRC32 value, and padding up to the configured System image size.

Serial Number Management

Hardware serial numbers can be generated automatically by specifying:

HW_SER:<gen>

or, depending on the parameter naming used by the target firmware:

HW_SERIAL:<gen>

Generated serial numbers are registered in:

config/system/serials/serialsInfo.csv

The registry stores information associated with each generated device, including:

• Serial Number
• Type
• Creation Date
• Board
• Device Type
• Year
• Month
• Extra Data
• Device Number

Device numbers are maintained independently for each OpenEPT device type. Therefore, for example, an Energy Profiler Probe and a Charger can both legitimately use device number 00000001. If @DEV_NUMBER is not specified, the utility determines the last device number assigned to the selected device type and assigns the next number. For example:

@DEVICE_TYPE:EPP

with existing EPP device numbers up to 00000005 results in the new device receiving:

00000006

A device number can also be selected explicitly:

@DEV_NUMBER:5

If the selected device already exists in the serial-number registry, its previously assigned serial number is reused. This allows configuration images to be regenerated for an existing physical device without assigning a new serial number. If the selected device does not exist, a new serial number is generated and registered.

Filesystem Utilities

The config/filesystem directory contains utilities for creating and extracting LittleFS filesystem images. A host directory can be converted into a binary LittleFS image while preserving its directory and file organization. For example:

examples/epp/fs/
├── config/
│   └── device.cfg
└── logs/
    └── raw.bin

can be converted into the filesystem region used by the Energy Profiler Probe. The reverse operation extracts an existing LittleFS binary image back into a regular host directory. The filesystem utilities are currently used by the Energy Profiler Probe. Devices that do not contain a filesystem, such as the OpenEPT Charger, use only the System image utilities.

Complete EPP Image Utilities

The config/image directory contains utilities for generating and extracting complete Energy Profiler Probe memory images. The EPP memory image consists of:

System region      4 KiB
LittleFS region  252 KiB
------------------------
Total             256 KiB

The image-generation utility combines the System image generated from systemParams.txt with the LittleFS image generated from the supplied filesystem directory. The extraction utility performs the reverse operation, separating the complete image into its System parameters and filesystem content.

Using OpenEPT Utilities

The utilities are implemented in Python and are intended to be executed from the config directory.

Step 1: Clone the Project from the Official GitHub Repository

There are two main methods for downloading the project from the official GitHub repository:

• Method 1: Use Git to clone the repository directly from the command line.
• Method 2: Navigate to the repository's GitHub page, click the green Code button, and select Download ZIP.

After cloning the repository, navigate to:

cd OpenEPT_Utilities/config

Step 2: Prepare System Parameters

Device-specific examples are located under:

examples/
├── charger/
└── epp/

The corresponding systemParams.txt file defines both generation metadata and firmware System parameters.

For example:

@DEVICE_TYPE:CHR
@SERIAL_EXTRA_DATA:1000000
@SYSTEM_SIZE:128

HW_SER:<gen>
FW_VER:1.0.0
CH_CURR:100
TERM_VOLT:4.2
TERM_CUR:3
MAX_CUR:5

The values should be adjusted according to the device for which the image is being generated.

Step 3: Generate a System Image

To generate a System image for the Charger:

python3 system/gen.py \
    examples/charger/systemParams.txt \
    charger_system.bin

The resulting binary image has the size specified by @SYSTEM_SIZE.

For example:

@SYSTEM_SIZE:128

produces a 128-byte System image.

The same utility can be used independently for an Energy Profiler Probe System region.

Step 4: Extract a System Image

A System image can be converted back into its human-readable parameter representation using:

python3 system/extract.py \
    charger_system.bin \
    charger_system_recovered.txt

This operation can be used to inspect or verify the contents of an existing System image.

Step 5: Generate a Complete EPP Image

The Energy Profiler Probe uses both a System region and a LittleFS filesystem region.

A complete EPP image can be generated using:

python3 image/gen.py \
    examples/epp/systemParams.txt \
    examples/epp/fs \
    epp_image.bin

The resulting image consists of the 4 KiB System region followed by the 252 KiB LittleFS region, producing a complete 256 KiB binary image.

The generated image can be verified with:

stat -c "%s bytes" epp_image.bin

The expected size is:

262144 bytes

Step 6: Extract a Complete EPP Image

A complete EPP memory image can be extracted using:

python3 image/extract.py \
    epp_image.bin \
    epp_extracted

The extraction process recovers both the System parameters and the LittleFS filesystem content.

Step 7: Generate and Extract a Filesystem Image

The LittleFS image can also be handled independently.

To generate a filesystem image:

python3 filesystem/gen.py \
    examples/epp/fs \
    filesystem.bin

To extract it:

python3 filesystem/extract.py \
    filesystem.bin \
    filesystem_extracted

These commands are useful when only the persistent filesystem content needs to be prepared or inspected.

Contributor guide

Step 1: Fork the Repository

To start contributing, fork the main repository to your own GitHub account:

1. Navigate to the repository you want to contribute to.
2. Click the Fork button in the upper-right corner.
3. This will create a copy of the repository under your GitHub account.

Step 2: Clone the Forked Repository

Once the repository is forked, clone it to your local machine:

# Replace <your-username> with your GitHub username
git clone https://github.com/<your-username>/<repository-name>.git
cd <repository-name>

Step 3: Create a New Branch

Before making changes, create a new branch based on the type of contribution:

• For new features, name the branch feature/<name>.
• For bug fixes, name the branch bug/<name>.

To create a branch:

# Replace <branch-name> with your branch name
git checkout -b <branch-name>

Step 4: Make Your Changes

Make the necessary changes to your branch. Test the utilities thoroughly to ensure your contribution does not introduce new issues.

Before making substantial changes, please review the project Documentation.

Step 5: Commit Your Changes

Once your changes are ready, stage and commit them:

git add .
git commit -m "Description of the changes made"

Step 6: Push Your Changes to Your Fork

Push the changes to your forked repository:

git push origin <branch-name>

Step 7: Create a Pull Request

1. Navigate to your forked repository on GitHub.
2. Switch to the branch you just pushed.
3. Click the Compare & pull request button.
4. Ensure the base repository and branch are correct.
5. Provide a descriptive title and detailed description for your pull request.
6. Add appropriate reviewers.
7. Submit the pull request.

Step 8: Collaborate on the Review Process

Once the pull request is submitted:

1. Wait for project maintainers to review your changes.
2. Address any feedback by making additional commits to your branch.
3. Once approved, the maintainers will merge your changes.

Step 9: Sync with the Main Repository

After your changes are merged, keep your fork synchronized with the main repository:

git remote add upstream https://github.com/<original-owner>/<repository-name>.git
git fetch upstream
git checkout main
git merge upstream/main

---

Documentation

For detailed developer instructions and additional OpenEPT materials, please see Documentation → Software under Materials on the official project website.

---

Acknowledgments