Initial commit

.pylintrc

@@ -0,0 +1,3 @@
+[MASTER]
+disable=
+    C0114, # missing-module-docstring

Pipfile

@@ -0,0 +1,19 @@
+[[source]]
+url = "https://pypi.python.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+canopen = "*"
+PyYAML = "*"
+"ruamel.yaml" = "*"
+click = "*"
+
+[dev-packages]
+pylint = "*"
+
+[requires]
+python_version = "3.8"
+
+[packages.pytablewriter]
+extras = [ "excel",]

README.md

@@ -0,0 +1,103 @@
+JUMP Battery Management System Specs
+======
+
+This repo is a collection of notes and tools made while reversing operation of the BMS in JUMP battery packs.
+
+Thanks to Jehu and Alex for documenting their work on waking up these batteries:
+
+- https://github.com/alex3dbros/LGH1ScooterPackPower  
+  Video detailing the hookup of micro-controller to can bus enabling battery pack.
+- https://www.youtube.com/watch?v=E87EcLeqIX0  
+  Source code for STM32 that enables battery output.
+
+## About the Battery
+
+The BMS speaks the CANopen protocol which makes it easy to fetch all data and interact with the device. At minimum read these two links if not familiar with CAN bus:
+
+  - https://en.wikipedia.org/wiki/CAN_bus
+  - https://en.wikipedia.org/wiki/CANopen  
+
+
+- CAN bus baud rate: 100000
+- CANopen device profile is unknown and likely vendor specific. The Energybus / Cia-454 profile for light electric vehicles is worthy of investigation but its not publicly available...can-OPEN ?
+- Default CANopen node id is 0x30 . Unable to change using the standard methods.
+- BMS starts up with 1 sec heartbeat in pre-operational mode.
+- 2 pre-mapped TPDOs available. Mapping is fixed.
+
+- Check Alex's repo for BMS connector [pinout](https://github.com/alex3dbros/LGH1ScooterPackPower/blob/master/JUMP%20Battery%20CON.png)
+
+  Pin | Function
+  --- | --------
+  1 - BLUE | 
+  2 - WHITE | 3.3v
+  3 - RED | 5v
+  4 - YELLOW | CAN HI
+  5 - GREEN | CAN LO
+  6 - BLACK | GND
+  7 - ORANGE | Power enable, connect to 8
+  8 - PINK | Power enable, connect to 7
+- Power/charge connector Molex ML-XT 4 pin ( should be compatible with Deutsch DT connectors )
+
+## Whats been discovered so far ?
+
+The main document spec document is available in HTML, Markdown, and YAML below.
+
+The most interesting stuff is located at index 0x2000 and higher.
+
+- Power output enable/disable
+- Battery Voltage
+- Battery Temperature
+- Howto pull data from BMS or have BMS push data to bus.
+
+File | Description 
+---- | -----------
+[jump_bms_spec.yaml](spec/jump_bms_spec.yaml) | Source document for all generated files. You want to edit this if you make any discoveries or changes.
+[jump_bms_spec.html](http://htmlpreview.github.io/?https://github.com/jonans/jump_battery_specs/blob/master/spec/spec.html) | HTML version document of the data
+[jump_bms_spec.md](spec/jump_bms_spec.md) | Markdown version of the data
+[jump_bms.eds](spec/jump_bms.eds) | EDS (cia 306) is the standard file format for describing CANopen devices. Its used by developers to get human readable variable names and automatically generate code. Its incomplete and non compliant but its just enough to work with the Python canopen library.
+
+## Tools
+
+Tools were created with Python under linux. Should run on windows but hasn't been tested and may need fixing.
+
+Tool | Description
+---- | -----
+tools/canopendump | Simple tool that dumps all device data to text or csv
+tools/bmsmonitor | Sample code that displays BMS status such as voltage, temperature, and some other unknown data points. Demonstrates configuring BMS to automatically push this data when it changes.
+tools/canspec | Takes the spec file jump_bms_spec.yaml and generates html, markdown, and eds files.
+
+### Setup environment
+
+Make sure you have python3 and pipenv installed. Run the following to install requirements
+and setup shell to run the tools.
+
+```shell
+pipenv install
+pipenv shell
+```
+
+## What can you do ?
+
+- Analyze the test scenarios and see what you can decode.
+- Get yourself a USB to CAN interface so you can poke around and run your own tests. Anything supported by the python-can library should work:
+
+  https://python-can.readthedocs.io/en/master/interfaces.html
+
+- Add anything you discover to the spec file jump_bms_spec.yaml and submit a pull request.
+
+## Test Scenarios
+
+Reversing the device is mostly about decoding the meaning of each data point on the BMS.
+
+We can dump all the data and compare the differences under various testing conditions to facilitate this:
+
+### Testing for temperature
+
+- Battery placed in freezer for about 2 hours and then removed.
+- Output off, no load, 34.3v
+
+1. [cold-1.csv](tests/cold-1.csv) - 5 min after,  room temp 24c
+1. [cold-2.csv](tests/cold-2.csv) - 30 min after, room temp 24c
+1. [cold-3.csv](tests/cold-3.csv) - 45 min after, room temp 23c
+1. [cold-4.csv](tests/cold-4.csv) - 60 min after, room temp 23c
+