pymagnum

https://pymagnum.readthedocs.io/en/stable/
Admin
Python implementation of a read-only interface to the Magnum Energy network for MS series inverter...
Tokens:8,971
Snippets:113
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Output with Reversed Wiring

Source: https://pymagnum.readthedocs.io/en/stable/_sources/installation.rst.txt

This output shows 'UNKNOWN' packets, which may indicate reversed wiring or other communication issues. Try reversing the wires on your setup.

```text
Length:42 UNKNOWN   =>7FFFFD9BFFFF11FFFDFF99EFD3E129FFFFFFFB4FFFFFFF87F75FE1D1F3FF6FB5E6FAD7C7C7F173C5D7BD
Length:29 UNKNOWN   =>0076F8FEFCFEFCFE7FFFFD9BFFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
Length:40 UNKNOWN   =>FFFF87F75FE1D1F3FF6FB5E6FAD7FF5FFF0FD70FBBFA6EE933FFBBEFC9E711FFF92FB5FF89EBFDFE
Length:42 UNKNOWN   =>7FFFFD9BFFFF11FFFDFF99EFD3E129FFFFFFFB4FFFFFFF87F75FE1D1F3FF6FB5E6FAD74341FFB7FBFFB9
Length:42 UNKNOWN   =>7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFFFFFF87F75FE1D1F3FF6FB5E6FAD7C3C3FFFFFFFFB7
Length:29 UNKNOWN   =>00F4D15C46FC9EFC7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
Length:42 UNKNOWN   =>FFFF87F75FE1D1F3FF6FB5E6FAD7FFFFFFFFA9FFFF7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
Length:42 UNKNOWN   =>FFFF87F75FE1D1F3FF6FB5E6FAD7FFFFFFFFFFFFFF7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
Length:29 UNKNOWN   =>FFFF87F75FE1D1F3FF6FB5E6FAD7FBCDD7FF23FFBF007AE85C8CFE24FC
Length:42 UNKNOWN   =>7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFFFFFF87F75FE1D1F3FF6FB5E6FAD7C7C7F173C5D7BD
Length:29 UNKNOWN   =>007AF45C8CFE24FC7FFFFD9BFFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
```

--------------------------------

### Install or Upgrade PyMagnum Package

Source: https://pymagnum.readthedocs.io/en/stable/_sources/installation.rst.txt

Use this command to install or upgrade the PyMagnum software package. Ensure pip is installed first.

```bash
sudo pip install --upgrade pymagnum
```

--------------------------------

### PyMagnum options file example

Source: https://pymagnum.readthedocs.io/en/stable/tools.html

An example configuration file for PyMagnum tools, demonstrating how to set options like device, interval, packets, and timeout. Comments are denoted by '#'.

```ini
# Alter these to suit
--device /dev/ttyUSB0
--interval 60
--packets 50
--timeout 0.005
# Remove # to enable the following
#--verbose
#--trace
#--nocleanup


```

--------------------------------

### Example Output of Successful Magtest

Source: https://pymagnum.readthedocs.io/en/stable/_sources/installation.rst.txt

This is an example of the expected output when the 'magtest --device all' command successfully identifies packets from the Magnum network.

```text
Length:21 REMOTE_A2 =>00003C04500F170601C8A5860100465000781478A2
Length:18 BMK_81    =>81550992FFC0089B0C77FFBFE11300390A01
Length:21 INVERTER  =>400000F60002780001003311241E6B000001025800
Length:21 REMOTE_A4 =>00003C04500F170601C8A58601001E1E00000000A4
Length: 6 AGS_A1    =>A102343A007C
Length:21 REMOTE_00 =>400000F60002770001003311241E6B000001025800
Length:21 REMOTE_00 =>400000F60002770001003311241E6B000001025800
.
.
Packets:50 in 1.10 seconds
```

--------------------------------

### Example Output of Successful Hardware Test

Source: https://pymagnum.readthedocs.io/en/stable/installation.html

This is an example of the output you might see when the `magtest` utility successfully detects and reads packets from the Magnum network.

```text
Length:21 REMOTE_A2 =>00003C04500F170601C8A5860100465000781478A2
Length:18 BMK_81    =>81550992FFC0089B0C77FFBFE11300390A01
Length:21 INVERTER  =>400000F60002780001003311241E6B000001025800
Length:21 REMOTE_A4 =>00003C04500F170601C8A58601001E1E00000000A4
Length: 6 AGS_A1    =>A102343A007C
Length:21 REMOTE_00 =>400000F60002770001003311241E6B000001025800
Length:21 REMOTE_00 =>400000F60002770001003311241E6B000001025800
.
.
Packets:50 in 1.10 seconds


```

--------------------------------

### Show magtest help message

Source: https://pymagnum.readthedocs.io/en/stable/tools.html

Displays the help message for the magtest tool, which is described in the installation instructions.

```bash
magtest --help
```

--------------------------------

### PyMagnum Options File Configuration

Source: https://pymagnum.readthedocs.io/en/stable/_sources/tools.rst.txt

An example of an options file for PyMagnum tools like magdump. This file allows configuration of options such as device, interval, packets, and timeout, with comments indicating usage.

```text
# Alter these to suit
    --device /dev/ttyUSB0
    --interval 60
    --packets 50
    --timeout 0.005
    # Remove # to enable the following
    #--verbose
    #--trace
    #--nocleanup
```

--------------------------------

### Install PyMagnum in a Virtual Environment (or ignore system package errors)

Source: https://pymagnum.readthedocs.io/en/stable/installation.html

If you encounter 'externally-managed-environment' errors with Python 3.11+, you can install PyMagnum in a virtual environment. Alternatively, use the `--break-system-packages` flag to bypass this check, though this is generally not recommended for system stability.

```bash
sudo pip install --upgrade pymagnum --break-system-packages
```

--------------------------------

### Show Installed PyMagnum Version

Source: https://pymagnum.readthedocs.io/en/stable/_sources/installation.rst.txt

Run this command to check the currently installed version of the PyMagnum package on your system.

```bash
sudo pip show pymagnum
```

--------------------------------

### Example Output of Hardware Test with Reverse Wiring

Source: https://pymagnum.readthedocs.io/en/stable/installation.html

This output shows 'UNKNOWN' packets, which may indicate that the wiring to the serial device is reversed or incorrect.

```text
Length:42 UNKNOWN   =>7FFFFD9BFFFF11FFFDFF99EFD3E129FFFFFFFB4FFFFFFF87F75FE1D1F3FF6FB5E6FAD7C7C7F173C5D7BD
Length:29 UNKNOWN   =>0076F8FEFCFEFCFE7FFFFD9BFFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
Length:40 UNKNOWN   =>FFFF87F75FE1D1F3FF6FB5E6FAD7FF5FFF0FD70FBBFA6EE933FFBBEFC9E711FFF92FB5FF89EBFDFE
Length:42 UNKNOWN   =>7FFFFD9BFFFF11FFFDFF99EFD3E129FFFFFFFB4FFFFFFF87F75FE1D1F3FF6FB5E6FAD74341FFB7FBFFB9
Length:42 UNKNOWN   =>7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFFFFFF87F75FE1D1F3FF6FB5E6FAD7C3C3FFFFFFFFB7
Length:29 UNKNOWN   =>00F4D15C46FC9EFC7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
Length:42 UNKNOWN   =>FFFF87F75FE1D1F3FF6FB5E6FAD7FFFF7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
Length:42 UNKNOWN   =>FFFF87F75FE1D1F3FF6FB5E6FAD7FFFFFFFFFFFFFF7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFF
Length:29 UNKNOWN   =>FFFF87F75FE1D1F3FF6FB5E6FAD7FBCDD7FF23FFBF007AE85C8CFE24FC
Length:42 UNKNOWN   =>7FFFFD99FFFF11FFFDFF99EFD3E129FFFFFFFB4FFFFFFF87F75FE1D1F3FF6FB5E6FAD7C7C7F173C5D7BD
Length:29 UNKNOWN   =>007AF45C8CFE24FC7FFFFD9BFFFF11FFFDFF99EFD3E129FFFFFFFB4FFF


```

--------------------------------

### Test with Increased Timeout and Specific Device

Source: https://pymagnum.readthedocs.io/en/stable/_sources/installation.rst.txt

If you encounter issues, try increasing the timeout value and specifying the serial device. Adjust the timeout value as needed for your setup.

```bash
magtest --timeout 0.005 --device /dev/ttyUSB0
```

--------------------------------

### Get Connected Devices

Source: https://pymagnum.readthedocs.io/en/stable/pymagnum-api.html

Use the getDevices() method to retrieve a list of connected Magnum Energy devices. Each device is represented by a dictionary containing its type, data, and optionally, trace information.

```python
devices = magnum_instance.getDevices()
print(devices)
```

--------------------------------

### Get Communication Device Name

Source: https://pymagnum.readthedocs.io/en/stable/pymagnum-api.html

Use getComm_Device() to obtain the name of the serial communication device currently in use by the Magnum instance. This is helpful for logging or generating status messages.

```python
comm_device = magnum_instance.getComm_Device()
print(f"Communication device: {comm_device}")
```

--------------------------------

### Initialize pyMagnum API

Source: https://pymagnum.readthedocs.io/en/stable/pymagnum-api.html

Instantiate the Magnum class to handle intercommunications with Magnum Energy devices. Customize connection parameters like the serial device, packet capture settings, and tracing.

```python
import magnum

# Default initialization
magnum_instance = magnum.Magnum()

# Custom initialization with specific parameters
magnum_instance_custom = magnum.Magnum(
    device='/dev/ttyUSB1',
    timeout=0.005,
    packets=100,
    cleanpackets=False,
    trace=True
)
```

--------------------------------

### Magdump command-line options

Source: https://pymagnum.readthedocs.io/en/stable/tools.html

Lists the regular and seldom-used command-line options for the magdump tool, including help, device, interval, verbose, packets, timeout, trace, and nocleanup.

```text
 -h, --help            show this help message and exit
 -d DEVICE, --device DEVICE
                       Serial device name (default: /dev/ttyUSB0)
 -i INTERVAL, --interval INTERVAL
                       Interval, in seconds, between dump records, in
                       seconds. 0 means once and exit. (default: 0)
 -v, --verbose         Display options at runtime (default: False)

 seldom used:
 --packets PACKETS     Number of packets to generate in reader (default: 50)
 --timeout TIMEOUT     Timeout for serial read (default: 0.005)
 --trace               Add most recent raw packet info to data (default: False)
 --nocleanup           Suppress clean up of unknown packets (default: False)

```

--------------------------------

### Magnum Class Initialization

Source: https://pymagnum.readthedocs.io/en/stable/_sources/pymagnum-api.rst.txt

Initializes the Magnum class, establishing a connection to a specified serial device and configuring communication parameters.

```APIDOC
## Magnum Class

### Description
Initializes the Magnum class to handle intercommunications with the network. It allows configuration of the serial device, packet handling, timeout, and tracing.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **device** (string) - Optional - The serial device to connect to. Defaults to `/dev/ttyUSB0`. If prefixed with `!`, the rest of the name is treated as a filename for debugging.
- **packets** (int) - Optional - How many packets to capture in one sample. Defaults to 50. Increase for better analysis, decrease for faster response.
- **cleanpackets** (boolean) - Optional - Allows the object to fix up two adjacent UNKNOWN packets by merging them. Defaults to True.
- **timeout** (float) - Optional - Time delay in fractions of a second to trigger the end of a packet. Defaults to 0.001.
- **trace** (boolean) - Optional - Enables adding a list of every packet processed since the last `getDevices()` call to the `trace` dictionary item. Defaults to False.
```

--------------------------------

### Show magdump help message

Source: https://pymagnum.readthedocs.io/en/stable/tools.html

Displays the help message for the magdump tool, outlining its available options and their descriptions.

```bash
magdump --help
```

--------------------------------

### Magdump to Mag2sql Schema Generation

Source: https://pymagnum.readthedocs.io/en/stable/_sources/tools.rst.txt

Demonstrates piping the JSON output from magdump to mag2sql to generate a draft MySQL schema definition. The output is redirected to a file named myschema.sql.

```bash
magdump | mag2sql > myschema.sql
```

--------------------------------

### Magdump Tool Help Options

Source: https://pymagnum.readthedocs.io/en/stable/_sources/tools.rst.txt

Displays the help message and available options for the magdump tool. Includes options for device selection, interval, verbosity, and less common settings.

```text
-h, --help            show this help message and exit
    -d DEVICE, --device DEVICE
                          Serial device name (default: /dev/ttyUSB0)
    -i INTERVAL, --interval INTERVAL
                          Interval, in seconds, between dump records, in
                          seconds. 0 means once and exit. (default: 0)
    -v, --verbose         Display options at runtime (default: False)

   seldom used:
    --packets PACKETS     Number of packets to generate in reader (default: 50)
    --timeout TIMEOUT     Timeout for serial read (default: 0.005)
    --trace               Add most recent raw packet info to data (default: False)
    --nocleanup           Suppress clean up of unknown packets (default: False)
```

--------------------------------

### Test Interconnect Hardware

Source: https://pymagnum.readthedocs.io/en/stable/_sources/installation.rst.txt

Execute this command to test the interconnect hardware by iterating over all serial devices. It should display packet information for connected Magnum networks.

```bash
magtest --device all
```

--------------------------------

### getDevices

Source: https://pymagnum.readthedocs.io/en/stable/_sources/pymagnum-api.rst.txt

Retrieves a list of connected devices and their associated data. If tracing is enabled, it also returns trace information.

```APIDOC
## getDevices()

### Description
Get a list of connected devices. Each device entry includes its type, a dictionary of its data, and optionally, trace information if enabled.

### Method
getDevices

### Parameters
None

### Return Value
List of device dictionaries. Each dictionary contains:
- **device** (string) - The type of device (e.g., INVERTER, REMOTE, AGS).
- **data** (dict) - A dictionary of name/value pairs for the device's fields.
- **trace** (list) - Optional. A list of tuples of every packet since the last call, present only if trace is set to True.
```

--------------------------------

### Show mag2sql help message

Source: https://pymagnum.readthedocs.io/en/stable/tools.html

Displays the help message for the mag2sql tool, which converts magdump JSON output to a MySQL definition.

```bash
mag2sql --help
```

--------------------------------

### getDevices()

Source: https://pymagnum.readthedocs.io/en/stable/pymagnum-api.html

Retrieves a list of connected devices on the network. Each device entry includes its type and a dictionary of its data fields.

```APIDOC
## getDevices()

Get a list of connected devices.

### Returns:

List of device dictionaries.
Each dictionary has two or, optionally, three items:
*   **device** (string) - One of `INVERTER`, `REMOTE`, `AGS`, `BMK`, `RTR`, `ACLD` or `PT100`.
*   **data** (dict) - A dictionary of name/value pairs for the fields in the device.
*   **trace** (list) - If trace is set to True then trace will have a list of tuples of every packet since last time invoked.
```

--------------------------------

### Retrieve Raw Network Packets

Source: https://pymagnum.readthedocs.io/en/stable/pymagnum-api.html

The getPackets() method retrieves raw network packets from the communication bus. This method is typically not used for general analysis but can be useful for low-level debugging.

```python
raw_packets = magnum_instance.getPackets()
print(raw_packets)
```

--------------------------------

### getPackets

Source: https://pymagnum.readthedocs.io/en/stable/_sources/pymagnum-api.rst.txt

Retrieves the raw packets from the network. This method is typically not used directly by end-users.

```APIDOC
## getPackets()

### Description
Retrieves the raw packets from the network. This method is not normally used by end-users.

### Method
getPackets

### Parameters
None

### Return Value
List of `tuple` objects. Each tuple contains:
- name of packet (string)
- bytes of packet (bytes)
- tuple of unpacked values for fields in packet (tuple)
```

--------------------------------

### getComm_Device

Source: https://pymagnum.readthedocs.io/en/stable/_sources/pymagnum-api.rst.txt

Retrieves the name of the communication device currently being used by the class instance.

```APIDOC
## getComm_Device()

### Description
Retrieves the name of the communication device for this instance of the class, which is useful for generating messages.

### Method
getComm_Device

### Parameters
None

### Return Value
String containing the name of the device (e.g., `/dev/ttyUSB0`).
```

--------------------------------

### getComm_Device()

Source: https://pymagnum.readthedocs.io/en/stable/pymagnum-api.html

Retrieves the name of the communication device associated with this class instance.

```APIDOC
## getComm_Device()

Retrieves the name of the communication device for this instance of of the class. This is useful for generating messages.

### Returns:

String containing name of device, such as `/dev/ttyUSB0`.
```
Tokens:
Raw