# openinverter CAN tool
[](../../actions/workflows/test.yml)
A tool to allow configuration and operating of openinverter systems for
electric vehicles over a CAN connection.
## Features
* Display all available modifiable parameters and read-only values supported by a given inverter firmware version
* Read a specified parameter/value
* Write a new value to a specified parameter
* Display the current value of each parameter/value on a given device
* Log a list of parameters to a CSV file at regular intervals
* Save and load all parameters to and from a JSON file
* Manage parameter to custom [CAN message mappings](https://github.com/davefiddes/openinverter-can-tool/blob/main/docs/can-mapping.md):
* Create, remove and list parameter mappings on a device
* Support maps with standard CAN 2.0a and extended CAN 2.0b frames
* Export and import mappings to a local JSON file
* Export mappings to DBC allowing easier debugging with [SavvyCAN](https://savvycan.com/)
* Upgrade firmware or recover devices over CAN
* Display the inverter serial number
* Command the inverter to:
* Start
* Stop
* Load parameters from flash
* Save parameters to flash
* Revert parameters to their default values
* Reset
* Scan a CAN bus for possible nodes
* Runs on Linux, Windows and MacOS with python 3.8+
* Support [shell completion](https://github.com/davefiddes/openinverter-can-tool/blob/main/docs/shell-completion.md) for commands and options for bash, zsh and fish shells
* Works with any CAN adapter supported by [python-can](https://pypi.org/project/python-can/)
* Supports [stm32-sine](https://github.com/jsphuebner/stm32-sine) 5.24.R or later
* Automatic parameter database download and caching (requires stm32-sine 5.27.R or later)
* Works with [Foccci/Clara](https://github.com/uhi22/ccs32clara) CCS controller and [Stm32-vcu](https://github.com/damienmaguire/Stm32-vcu) (a.k.a. Zombieverter VCU)
## Installation
The most recent release may be installed using pip:
```text
pip install openinverter_can_tool
```
To install directly from github:
```text
git clone https://github.com/davefiddes/openinverter_can_tool.git
cd openinverter_can_tool
pip install -e .
```
### Linux
Linux users may reduce the potential of package conflicts by installing python dependencies from their package manager. This should be done before running `pip`.
#### Fedora
```text
sudo dnf install python3-setuptools python3-pip python3-click python3-can python3-appdirs
```
#### Ubuntu/Debian
```text
sudo apt install python3-setuptools python3-pip python3-click python3-can python3-appsdirs
```
## Configuration
Before the tool can be used the CAN interface adapter needs to be configured. To do this create `~/.canrc` on Linux or `%USERPROFILE%/can.conf` on Windows. Details on interfaces supported and the configuration file format can be found in the [python-can](https://python-can.readthedocs.io/en/stable/installation.html) documentation.
An example configuration file for a [SocketCAN](https://python-can.readthedocs.io/en/stable/interfaces/socketcan.html) compatible adapter on Linux would look like:
```text
[default]
interface = socketcan
channel = can0
bitrate = 500000
```
Note: Before the tool can on Linux run the SocketCAN network interface needs to be started:
```text
sudo ip link set can0 up type can bitrate 500000
```
An example configuration file for a [SLCAN](https://python-can.readthedocs.io/en/stable/interfaces/slcan.html) adapter such as [GVRET](https://github.com/collin80/GVRET) on Windows would look like:
```text
[default]
interface = slcan
channel = COM8
bitrate = 500000
```
Tested interfaces:
* [Innomaker USB2CAN](https://www.inno-maker.com/product/usb2can-cable/) CAN interface in Linux.
* [GVRET](https://github.com/collin80/GVRET) CAN interface using `slcan` in Linux
Let me know if you have used a particular CAN interface successfully and I can expand this list.
## Usage
The parameters and values supported by a given openinverter firmware will often vary from release to release and by firmware type (e.g. Sine to Field Oriented Control(FOC)). The tool comes with a small collection of parameter databases for recent openinverter releases. These can be found in the parameter-databases directory in the install location. Versions of stm32-sine from 5.25.R and onwards support automatic download of parameter databases and the database option does not need to be specified.
To get the usage information for the tool run the `oic` command with no parameters:
```text
Usage: oic [OPTIONS] COMMAND [ARGS]...
openinverter CAN Tool allows querying and setting configuration of inverter
parameters over a CAN connection
Options:
-d, --database FILE Override the openinverter JSON parameter database to
use
-c, --context TEXT Which python-can configuration context to use
-n, --node INTEGER The CAN SDO node ID to communicate with [env var:
OIC_NODE; default: 1]
-t, --timeout FLOAT Response timeout in seconds [default: 1.0]
--version Show the version and exit.
--help Show this message and exit.
Commands:
cache Parameter database cache management commands
can Manage parameter to CAN message mappings on a device
cmd Execute a command on a device
dumpall Dump the values of all available parameters and values
listparams List all available parameters and values
load Load all parameters from json IN_FILE
log Log the value of PARAMS from the device periodically in CSV...
read Read the value of PARAM from the device
save Save all parameters in json to OUT_FILE
scan Scan the CAN bus for available nodes
serialno Read the device serial number.
upgrade Upgrade the device firmware.
write Write the value to the parameter PARAM on the device
```
To read a specific parameter from 5.24.R firmware:
```text
$ oic -d parameter-databases/stm32-sine.5.24.R-foc.json read brakeregen
brakeregen: -13 [%]
```
To write a new value to a parameter with 5.27.R or later firmware with automatic database download:
```text
oic write brakeregen -30.5
```
Values may be changed using symbolic names:
```text
oic write potmode DualChannel
oic write pinswap PWMOutput13,PWMOutput23
```
The list of allowed values for a given parameter can be found using the `listparams` command.
## Development
If you want to be able to change the code while using it, clone it then install
it in development mode:
```text
git clone https://github.com/davefiddes/openinverter_can_tool.git
cd openinverter_can_tool
virtualenv venv
. venv/bin/activate
pip install -e .[dev,test]
pre-commit install
```
To exit the virtualenv environment use use the system installed `oic` run `dectivate`. To resume development operation the virtualenv can be restarted by running:
```text
. venv/bin/activate
```
Unit tests and python code linting can be run on all supported python versions using the `tox` test framework.
Code is written to conform to PEP8 conventions and enforced by `pylint` and `flake8` linting.
Contributions are most welcome. Before raising a pull request please install and use the pre-commit git hooks provided to ensure code conforms to the project style. Thanks!
Raw data
{
"_id": null,
"home_page": "https://github.com/davefiddes/openinverter-can-tool",
"name": "openinverter-can-tool",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "openinverter, canopen",
"author": "David J. Fiddes",
"author_email": "D.J@fiddes.net",
"download_url": "https://files.pythonhosted.org/packages/e5/1b/87f41ca1423c8ea9d1e6e0ebddcec4a7e0e06de802ab8b8ff9ffffbfb03a/openinverter_can_tool-0.2.1.tar.gz",
"platform": null,
"description": "# openinverter CAN tool\n\n[](../../actions/workflows/test.yml)\n\n\n\nA tool to allow configuration and operating of openinverter systems for\nelectric vehicles over a CAN connection.\n\n## Features\n\n* Display all available modifiable parameters and read-only values supported by a given inverter firmware version\n* Read a specified parameter/value\n* Write a new value to a specified parameter\n* Display the current value of each parameter/value on a given device\n* Log a list of parameters to a CSV file at regular intervals\n* Save and load all parameters to and from a JSON file\n* Manage parameter to custom [CAN message mappings](https://github.com/davefiddes/openinverter-can-tool/blob/main/docs/can-mapping.md):\n * Create, remove and list parameter mappings on a device\n * Support maps with standard CAN 2.0a and extended CAN 2.0b frames\n * Export and import mappings to a local JSON file\n * Export mappings to DBC allowing easier debugging with [SavvyCAN](https://savvycan.com/)\n* Upgrade firmware or recover devices over CAN\n* Display the inverter serial number\n* Command the inverter to:\n * Start\n * Stop\n * Load parameters from flash\n * Save parameters to flash\n * Revert parameters to their default values\n * Reset\n* Scan a CAN bus for possible nodes\n* Runs on Linux, Windows and MacOS with python 3.8+\n* Support [shell completion](https://github.com/davefiddes/openinverter-can-tool/blob/main/docs/shell-completion.md) for commands and options for bash, zsh and fish shells\n* Works with any CAN adapter supported by [python-can](https://pypi.org/project/python-can/)\n* Supports [stm32-sine](https://github.com/jsphuebner/stm32-sine) 5.24.R or later\n* Automatic parameter database download and caching (requires stm32-sine 5.27.R or later)\n* Works with [Foccci/Clara](https://github.com/uhi22/ccs32clara) CCS controller and [Stm32-vcu](https://github.com/damienmaguire/Stm32-vcu) (a.k.a. Zombieverter VCU)\n\n## Installation\n\nThe most recent release may be installed using pip:\n\n```text\n pip install openinverter_can_tool\n```\n\nTo install directly from github:\n\n```text\n git clone https://github.com/davefiddes/openinverter_can_tool.git\n cd openinverter_can_tool\n pip install -e .\n```\n\n### Linux\n\nLinux users may reduce the potential of package conflicts by installing python dependencies from their package manager. This should be done before running `pip`.\n\n#### Fedora\n\n```text\n sudo dnf install python3-setuptools python3-pip python3-click python3-can python3-appdirs\n```\n\n#### Ubuntu/Debian\n\n```text\n sudo apt install python3-setuptools python3-pip python3-click python3-can python3-appsdirs\n```\n\n## Configuration\n\nBefore the tool can be used the CAN interface adapter needs to be configured. To do this create `~/.canrc` on Linux or `%USERPROFILE%/can.conf` on Windows. Details on interfaces supported and the configuration file format can be found in the [python-can](https://python-can.readthedocs.io/en/stable/installation.html) documentation.\n\nAn example configuration file for a [SocketCAN](https://python-can.readthedocs.io/en/stable/interfaces/socketcan.html) compatible adapter on Linux would look like:\n\n```text\n[default]\ninterface = socketcan\nchannel = can0\nbitrate = 500000\n```\n\nNote: Before the tool can on Linux run the SocketCAN network interface needs to be started:\n\n```text\n sudo ip link set can0 up type can bitrate 500000\n```\n\nAn example configuration file for a [SLCAN](https://python-can.readthedocs.io/en/stable/interfaces/slcan.html) adapter such as [GVRET](https://github.com/collin80/GVRET) on Windows would look like:\n\n```text\n[default]\ninterface = slcan\nchannel = COM8\nbitrate = 500000\n```\n\nTested interfaces:\n\n* [Innomaker USB2CAN](https://www.inno-maker.com/product/usb2can-cable/) CAN interface in Linux.\n* [GVRET](https://github.com/collin80/GVRET) CAN interface using `slcan` in Linux\n\nLet me know if you have used a particular CAN interface successfully and I can expand this list.\n\n## Usage\n\nThe parameters and values supported by a given openinverter firmware will often vary from release to release and by firmware type (e.g. Sine to Field Oriented Control(FOC)). The tool comes with a small collection of parameter databases for recent openinverter releases. These can be found in the parameter-databases directory in the install location. Versions of stm32-sine from 5.25.R and onwards support automatic download of parameter databases and the database option does not need to be specified.\n\nTo get the usage information for the tool run the `oic` command with no parameters:\n\n```text\n Usage: oic [OPTIONS] COMMAND [ARGS]...\n\n openinverter CAN Tool allows querying and setting configuration of inverter\n parameters over a CAN connection\n\n Options:\n -d, --database FILE Override the openinverter JSON parameter database to\n use\n -c, --context TEXT Which python-can configuration context to use\n -n, --node INTEGER The CAN SDO node ID to communicate with [env var:\n OIC_NODE; default: 1]\n -t, --timeout FLOAT Response timeout in seconds [default: 1.0]\n --version Show the version and exit.\n --help Show this message and exit.\n\n Commands:\n cache Parameter database cache management commands\n can Manage parameter to CAN message mappings on a device\n cmd Execute a command on a device\n dumpall Dump the values of all available parameters and values\n listparams List all available parameters and values\n load Load all parameters from json IN_FILE\n log Log the value of PARAMS from the device periodically in CSV...\n read Read the value of PARAM from the device\n save Save all parameters in json to OUT_FILE\n scan Scan the CAN bus for available nodes\n serialno Read the device serial number.\n upgrade Upgrade the device firmware.\n write Write the value to the parameter PARAM on the device\n```\n\nTo read a specific parameter from 5.24.R firmware:\n\n```text\n $ oic -d parameter-databases/stm32-sine.5.24.R-foc.json read brakeregen\n brakeregen: -13 [%]\n```\n\nTo write a new value to a parameter with 5.27.R or later firmware with automatic database download:\n\n```text\n oic write brakeregen -30.5\n```\n\nValues may be changed using symbolic names:\n\n```text\n oic write potmode DualChannel\n oic write pinswap PWMOutput13,PWMOutput23\n```\n\nThe list of allowed values for a given parameter can be found using the `listparams` command.\n\n## Development\n\nIf you want to be able to change the code while using it, clone it then install\nit in development mode:\n\n```text\n git clone https://github.com/davefiddes/openinverter_can_tool.git\n cd openinverter_can_tool\n virtualenv venv\n . venv/bin/activate\n pip install -e .[dev,test]\n pre-commit install\n```\n\nTo exit the virtualenv environment use use the system installed `oic` run `dectivate`. To resume development operation the virtualenv can be restarted by running:\n\n```text\n . venv/bin/activate\n```\n\nUnit tests and python code linting can be run on all supported python versions using the `tox` test framework.\n\nCode is written to conform to PEP8 conventions and enforced by `pylint` and `flake8` linting.\n\nContributions are most welcome. Before raising a pull request please install and use the pre-commit git hooks provided to ensure code conforms to the project style. Thanks!\n",
"bugtrack_url": null,
"license": null,
"summary": "Tool to configure and operate openinverter systems over CAN",
"version": "0.2.1",
"project_urls": {
"Bug Reports": "https://github.com/davefiddes/openinverter-can-tool/issues",
"Homepage": "https://github.com/davefiddes/openinverter-can-tool",
"Source": "https://github.com/davefiddes/openinverter-can-tool"
},
"split_keywords": [
"openinverter",
" canopen"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1d91028bf74aa099e6e938d4292c250f91aa4cb4c117eba2c826c1bbac8bc06a",
"md5": "47a7ffeca9099ab47cd1a6ff366b7284",
"sha256": "8659cba20e478726d5e606b18fa25eb676051b0287fbcea4c895bf3251edcd4f"
},
"downloads": -1,
"filename": "openinverter_can_tool-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47a7ffeca9099ab47cd1a6ff366b7284",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 310638,
"upload_time": "2024-09-21T13:48:38",
"upload_time_iso_8601": "2024-09-21T13:48:38.968632Z",
"url": "https://files.pythonhosted.org/packages/1d/91/028bf74aa099e6e938d4292c250f91aa4cb4c117eba2c826c1bbac8bc06a/openinverter_can_tool-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e51b87f41ca1423c8ea9d1e6e0ebddcec4a7e0e06de802ab8b8ff9ffffbfb03a",
"md5": "60f2d01cbdbdcf230de8c8111014be5e",
"sha256": "5e1d69fc61ced8274b732f65fabcc07ccda18e0460bf9391f347990f29bbf2d2"
},
"downloads": -1,
"filename": "openinverter_can_tool-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "60f2d01cbdbdcf230de8c8111014be5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 319153,
"upload_time": "2024-09-21T13:48:40",
"upload_time_iso_8601": "2024-09-21T13:48:40.781887Z",
"url": "https://files.pythonhosted.org/packages/e5/1b/87f41ca1423c8ea9d1e6e0ebddcec4a7e0e06de802ab8b8ff9ffffbfb03a/openinverter_can_tool-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-21 13:48:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davefiddes",
"github_project": "openinverter-can-tool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "openinverter-can-tool"
}
JSON
