pySunSpec2

https://github.com/sunspec/pysunspec2
Admin
pySunSpec2 is a Python package that provides objects and applications for interaction with SunSpec...
Tokens:91,027
Snippets:605
Trust Score:7.8
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### ModbusClientTCP Usage Example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-modbus.md

Demonstrates basic read/write operations and a TLS-secured connection setup using ModbusClientTCP.

```python
from sunspec2.modbus.modbus import ModbusClientTCP, FUNC_READ_INPUT

c = ModbusClientTCP(slave_id=1, ipaddr='127.0.0.1', ipport=502, timeout=2.0)
data = c.read(40000, 3, op=FUNC_READ_INPUT)
c.write(40002, b'\x12\x34')
c.disconnect()

# TLS
ct = ModbusClientTCP(ipaddr='127.0.0.1', ipport=802, tls=True,
                     cafile='/path/ca.crt', certfile='/path/client.crt', keyfile='/path/client.key')
try:
    ct.read(40000, 2)
except ModbusClientError as e:
    print('TLS connection failed:', e)
finally:
    ct.close()
```

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

### Install pySunSpec2 from setup.py

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Install from the local setup.py file. The second command is for when the Python path isn't configured.

```bash
C:\pysunspec2> python -m pip install .
```

```bash
C:\pysunspec2> c:\Python37\python.exe -m pip install .
```

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

### SunSpecModbusClientDeviceRTU Usage Example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-client.md

A complete example showing how to initialize, open, scan, read data from, and close a Modbus RTU device.

```python
import sunspec2.modbus.client as client

d = client.SunSpecModbusClientDeviceRTU(slave_id=1, name='COM2', baudrate=9600, timeout=1.0)
d.open()
d.scan(full_model_read=True)

common = d.common[0]
common.read()
print(common.Mn.value)          # manufacturer

d.close()
```

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

### SunSpecModbusClientDeviceTCP Usage Example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-client.md

Demonstrates initializing a device, scanning for models, reading/writing points, and configuring a TLS-secured connection.

```python
import sunspec2.modbus.client as client

d = client.SunSpecModbusClientDeviceTCP(slave_id=1, ipaddr='127.0.0.1', ipport=8502,
                                        timeout=2.0, trace_func=print)
d.scan()
print(d.models)

d.DERVoltVar[0].read()          # Group.read -> register read
d.DERVoltVar[0].Ena.value = 1   # Point set
d.DERVoltVar[0].write()         # writes only dirty points
d.close()

# TLS / Modbus/TCP Security
dtls = client.SunSpecModbusClientDeviceTCP(ipaddr='127.0.0.1', ipport=802, tls=True,
                                           cafile='ca.crt', certfile='client.crt', keyfile='client.key')
```

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

### Install pySunSpec2 with pip

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Install the package and its models using pip. Requires Python >= 3.5.

```bash
pip install pysunspec2
```

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

### CSV I/O example with sunspec2.spreadsheet

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/spreadsheet.md

Shows converting a model definition to CSV using ss.to_csv and reading it back with ss.from_csv. The example uses filename='model_705.csv' for both operations.

```python
import sunspec2.spreadsheet as ss

# model definition -> spreadsheet -> CSV
ss.to_csv(model_def, filename='model_705.csv')

# CSV -> model definition
md = ss.from_csv(filename='model_705.csv')
```

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

### set_read_func(self, func, arg=None) / set_write_func(self, func, arg=None)

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/point.md

Installs hooks that are called at the start of get_value (read func) or at the end of set_value (write func).

```APIDOC
## set_read_func(self, func, arg=None) / set_write_func(self, func, arg=None)

### Description
Installs hooks that are called at the start of get_value (read func) or at the end of set_value (write func).

### Method
Python method

### Signature
`set_read_func(self, func, arg=None)` / `set_write_func(self, func, arg=None)`

### Parameters
- **func** (callable) - Required - Called with (model, arg) on read (write_func)
- **arg** (any) - Optional, default None - Argument passed to func

### Returns
None
```

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

### get_model_info usage example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/device.md

Shows how to call get_model_info and print the model name and group count flag.

```python
model_def, has_count, glen = device.get_model_info(705)
print(model_def['group']['name'], has_count, glen)
```

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

### FileClientDevice.__init__

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/file-client.md

Constructor for the FileClientDevice class. Initializes the device with an optional filename, starting register address, and model class.

```APIDOC
## FileClientDevice.__init__

### Description
Initializes a new FileClientDevice instance. The filename points to a JSON device image file; when None, scan() does nothing.

### Method
Constructor

### Signature
```python
def __init__(self, filename=None, addr=40002, model_class=FileClientModel):
```

### Parameters
- **filename** (str / None) - Optional - Path to a JSON device image file; when None, scan() does nothing.
- **addr** (int) - Optional - Starting register address assigned to the first model. Default: 40002.
- **model_class** (type) - Optional - Model class used by scan. Default: FileClientModel.

```

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

### Building a device in-memory from a JSON snapshot

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/device.md

Example of building a device in-memory from a JSON snapshot dict using the Device class and _set_dict, then printing the JSON representation. The Device class is a no-op until subclassed; RTU/TCP/file subclasses provide the transport.

```python
import sunspec2.device as device

# Building a device in-memory from a JSON snapshot dict
d = device.Device()
d._set_dict({'name': 'inv1', 'models': [{'ID': 706, 'L': 66}]})

# No-op until subclassed; RTU/TCP/file subclasses provide the transport
print(d.get_json())
```

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

### Usage example for device.Model

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/model.md

Shows how to create a Model instance, access a repeating group, check for errors, and serialize to Modbus registers. Also demonstrates that construction errors are recorded in error_info rather than raised.

```python
from sunspec2 import device

# Load model 705 (DERVoltVar) from the installed definitions
m = device.Model(model_id=705, model_addr=40002, model_len=154)

# Repeating group 'Crv' is a list; first element is index 0
print(m.Crv[0].get_dict())
print(m.error_info or 'model OK')

# Serialize back to registers
regs = m.get_mb()

# Errors during construction are recorded, not raised
m2 = device.Model(model_id=999999)   # no such definition in the model set
print(m2.error_info)                 # 'Model definition not found for model 999999'
```

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

### Scanning a TCP Device

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-client.md

Example of initializing a SunSpecModbusClientDeviceTCP instance and performing a scan with a progress callback and custom delay.

```python
d = client.SunSpecModbusClientDeviceTCP(slave_id=1, ipaddr='127.0.0.1', ipport=8502)
d.scan(progress=lambda msg: print(msg), delay=0.1, full_model_read=False)
```

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

### FileClientDevice.__init__

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/file-client.md

Constructor for FileClientDevice. Initializes the parent Device with the given model_class, generates a unique device ID, and stores the filename and starting register address.

```python
def __init__(self, filename=None, addr=40002, model_class=FileClientModel):
    device.Device.__init__(self, model_class=model_class)
    self.did = str(uuid.uuid4())
    self.filename = filename
    self.addr = addr
```

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

### Read Input Registers Example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/endpoints.md

Example of reading 3 registers at the SunSpec base address using the TCP client with function code 4.

```python
# Read 3 registers at SunSpec base address using input registers
tcp = ModbusClientTCP(slave_id=1, ipaddr='127.0.0.1')
data = tcp.read(40000, 3, op=FUNC_READ_INPUT)
```

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

### create_unimpl_value usage example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/mb.md

Shows creating an unimplemented UINT16 value (b'\xff\xff') and catching ValueError for an unknown type.

```python
b = mb.create_unimpl_value(mdef.TYPE_UINT16)         # b'\xff\xff'
try:
    mb.create_unimpl_value('nope')
except ValueError as e:
    print(e)
```

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

### Error handling example: Missing openpyxl and read-only workbook

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/xlsx.md

Shows how creation of ModelWorkbook raises ImportError when openpyxl is not installed, and how writing to a read-only workbook raises ValueError when calling set_cell.

```python
from sunspec2.xlsx import ModelWorkbook

try:
    wb = ModelWorkbook()          # without openpyxl installed this raises
except ImportError as e:
    print('openpyxl required:', e)

wb = ModelWorkbook(filename='readonly.xlsx')
try:
    wb.set_cell(wb.wb.active, 1, 1, 'x')
except ValueError as e:
    print('read-only workbook:', e)
```

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

### to_spreadsheet Usage

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/spreadsheet.md

Example of converting a model definition dictionary into a spreadsheet structure.

```python
spreadsheet = ss.to_spreadsheet(model_def)   # header + data rows
```

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

### Get point value, scale factor, and computed value

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Shows how to read the base value, scale factor value, and computed value (base value scaled by the scale factor) from a point object. The examples use a Device object 'd', Model 'DERMeasureAC[0]', and Point 'LLV'.

```python
>>> d.DERMeasureAC[0].LLV.value
2403
```

```python
>>> d.DERMeasureAC[0].LLV.sf_value
-1
```

```python
>>> d.DERMeasureAC[0].LLV.cvalue
240.3
```

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

### from_spreadsheet Usage

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/spreadsheet.md

Example of converting a spreadsheet object into a model definition dictionary.

```python
model_def = ss.from_spreadsheet(spreadsheet)
```

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

### Modbus RTU client usage example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-modbus.md

Example of creating a Modbus RTU client and performing read and write operations. The read call with an invalid address raises an exception that is caught and printed.

```python
from sunspec2.modbus.modbus import modbus_rtu_client, PARITY_NONE

rtu = modbus_rtu_client(name='/dev/ttyUSB0', baudrate=9600, parity=PARITY_NONE, timeout=1.0)
regs = rtu.read(1, 40000, 3)             # read 3 registers at base address
rtu.write(1, 41234, (1234).to_bytes(2, 'big'))   # write one register (0x06)
try:
    rtu.read(1, 9999, 1)
except Exception as e:
    print(type(e).__name__, e)
```

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

### suns CLI usage examples for tcp, rtu, and file transports

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/suns-cli.md

Three bash commands showing how to run the `suns` tool with different transports: 'tcp' for Modbus TCP, 'rtu' for Modbus RTU, and 'file' for a device image file. The commands use the options documented in the options table.

```bash
# Dump a Modbus TCP device
suns -t tcp -a 1 -i 192.168.1.10 -P 502 -T 2.0
```

```bash
# Dump a Modbus RTU device
suns -t rtu -a 1 -p /dev/ttyUSB0 -b 9600 -T 1.5
```

```bash
# Dump a device image file
suns -t file -m device_1547.json
```

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

### set_model_defs_path usage example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/device.md

Shows how to set a custom model definition search path. Subsequent get_model_def() calls search those directories.

```python
device.set_model_defs_path(['/opt/sunspec/models', './custom_models'])
# Subsequent get_model_def() calls search those directories ('.', 'json', 'smdx' subdirs)
```

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

### Usage example: Build and read an XLSX workbook with ModelWorkbook

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/xlsx.md

Creates a ModelWorkbook with header color 'c0c0c0', writes a model definition (e.g. {'id': 705, 'group': {...}}) to it, saves as 'models_705.xlsx', then reads the file back and prints each model ID and its group name.

```python
import sunspec2.mdef as mdef
from sunspec2.xlsx import ModelWorkbook

# Build a workbook from a model definition
wb = ModelWorkbook(params={'hdr_color': 'c0c0c0'})
wb.to_xlsx(model_def)            # e.g. model_def = {'id': 705, 'group': {...}}
wb.save('models_705.xlsx')

# Read models back from an existing workbook
wb2 = ModelWorkbook(filename='models_705.xlsx')
for mid in wb2.get_models():
    md = wb2.from_xlsx(mid=mid)
    print(mid, md['group']['name'])
```

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

### Enable function and write to device

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Sets the Ena value to 1 and writes to the device to enable the function. Note: the example uses d.write() instead of vv.write().

```python
>>> vv.Ena.value = 1
>>> d.write()
```

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

### Example usage of value and cvalue with scale factor

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/point.md

Shows how `value` and `cvalue` interact with a scale factor. Setting `value` to 2403 yields `cvalue` 240.3; setting `cvalue` to 245.1 stores base value 2451.

```python
p = Point(pdef)                    # pdef with 'sf': -1
p.sf_value = -1
p.value = 2403
print(p.cvalue)                    # 240.3
p.cvalue = 245.1
print(p.value)                     # 2451
```

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

### Example usage of get_model_def with error handling

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/device.md

Shows how to call get_model_def with a model ID (705) and handle mdef.ModelDefinitionError. Demonstrates that with mapping=True the group dict includes 'point_defs'/'group_defs', while mapping=False omits them.

```python
try:
    md = device.get_model_def(705)
    print(md['group']['name'])   # 'DERVoltVar'
except mdef.ModelDefinitionError as e:
    print('definition unavailable:', e)

# without mapping, group dicts lack 'point_defs'/'group_defs'
md_raw = device.get_model_def(705, mapping=False)
```

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

### Set point value and computed value

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Shows how to set the base value and the computed value on a point. Setting the computed value uses the scale factor to calculate the base value. The examples use a Device object 'd', Model 'DEREnterService[0]', and Point 'ESVHi'.

```python
>>> d.DEREnterService[0].ESVHi.value = 2450
```

```python
>>> d.DEREnterService[0].ESVHi.cvalue
245.0
```

```python
>>> d.DEREnterService[0].ESVHi.cvalue = 245.1
```

```python
>>> d.DEREnterService[0].ESVHi.value
2451
```

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

### Write Holding Registers Example

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/endpoints.md

Example of writing 3 contiguous holding registers starting at address 41234.

```python
# Write 3 contiguous holding registers at address 41234
payload = b'\x00\x01\x00\x02\x00\x03'
rtu.write(1, 41234, payload, max_write_count=123)
```

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

### Get point as value

Source: https://github.com/sunspec/pysunspec2/blob/master/sunspec2/docs/pysunspec.rst

Retrieves the raw value of a point after setting its computed value. The example shows the result 2451 for the ESVHi point.

```python
>>> d.DEREnterService[0].ESVHi.value
2451
```

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

### Get point as cvalue

Source: https://github.com/sunspec/pysunspec2/blob/master/sunspec2/docs/pysunspec.rst

Retrieves the computed value (cvalue) of a point after setting its raw value. The example shows the result 245.0 for the ESVHi point.

```python
>>> d.DEREnterService[0].ESVHi.cvalue
245.0
```

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

### Initialize device image file

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Creates a FileClientDevice object from a device image file named 'model_702_data.json'.

```python
>>> import sunspec2.file.client as client
>>> d = client.FileClientDevice('model_702_data.json')
```

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

### Get computed value on a point with scale factor -1

Source: https://github.com/sunspec/pysunspec2/blob/master/sunspec2/docs/pysunspec.rst

Shows how to retrieve the computed value (cvalue) of a point, where the scale factor is -1. The example uses the DERMeasureAC model and the LLV point.

```python
>>> d.DERMeasureAC[0].LLV.cvalue
240.3
```

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

### Scan device image and access models

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/file-client.md

Imports file_client, creates a FileClientDevice from 'device_1547.json', scans it, prints models and model list, accesses a point value, and closes the device.

```python
import sunspec2.file.client as file_client

d = file_client.FileClientDevice('device_1547.json')
d.scan()

# models keyed by id and by name
print(d.models)
for m in d.model_list:
    print(m.model_id, m.gname, m.get_dict())

# Access points as attributes (values come from the image file)
if 1 in d.models:
    print(d.common[0].Mn.value)

d.close()
```

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

### Device.__init__

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/device.md

Constructor for the Device base class. Initializes the device with an empty model registry and sets the model class used for scanning.

```APIDOC
## Device.__init__

### Description
Initializes a new Device instance with empty model storage and a configurable model class.

### Parameters
- **model_class** (type: Model class) - Optional - The class to use when creating model instances during scanning. Defaults to Model.

### Returns
None

### Example
```python
d = device.Device()
```
```

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

### Point.__init__ constructor signature

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/point.md

Constructor for a Point instance. Accepts optional point definition, model, group, offsets, and initial data. When pdef is given, it resolves sf_required, sf_value, info, len, static, standards, and detail attributes.

```python
def __init__(self, pdef=None, model=None, group=None, model_offset=0, data=None, data_offset=0):
```

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

### Get points in DERVoltVar model

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Gets the points present in model 705 (DERVoltVar) on the device. The points are contained in an ordered dictionary.

```python
>>> d.DERVoltVar[0].points
OrderedDict([('ID', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C2E0>),
             ('L', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C2B0>),
             ('Ena', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C280>),
             ('CrvSt', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C250>),
             ('AdptCrvReq', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C220>),
             ('AdptCrvRslt', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C0A0>),
             ('NPt', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C0D0>),
             ('NCrv', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C100>),
             ('RvrtTms', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C130>),
             ('RvrtRem', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C160>),
             ('RvrtCrv', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C190>),
             ('V_SF', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C1C0>),
             ('DeptRef_SF', <__main__.SunSpecModbusClientPoint object at 0x000001FD7A59C1F0>)])
```

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

### SunSpecModbusClientDevice.__init__

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-client.md

Initializes a new SunSpecModbusClientDevice instance with a default model class, a unique device ID, retry count, and base address list for scanning.

```APIDOC
## SunSpecModbusClientDevice.__init__

### Description
Initializes a new SunSpecModbusClientDevice instance. Sets the device ID to a random UUID, retry count to 2, and base address list to [40000, 0, 50000]. The base address is initially None.

### Method
Constructor

### Signature
```python
def __init__(self, model_class=SunSpecModbusClientModel)
```

### Parameters
- **model_class** (class) - Optional - The model class to use for creating model objects. Defaults to SunSpecModbusClientModel.

### Attributes
| Attribute | Default | Meaning |
|---|---|---|
| `retry_count` | `2` | Retry count (declared; not referenced by scan in this version) |
| `base_addr_list` | `[40000, 0, 50000]` | SunSpec map base addresses probed by `scan()` |
| `base_addr` | `None` | Address where the `'SunS'` identifier was found |
```

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

### Get groups in DERVoltVar model

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Gets the groups present in model 705 (DERVoltVar) on the device. The groups are contained in an ordered dictionary, with repeating groups represented as a list of groups.

```python
>>> d.DERVoltVar[0].groups
OrderedDict([('Crv', [<__main__.SunSpecModbusClientGroup object at 0x000001FD7A58EFA0>,
                      <__main__.SunSpecModbusClientGroup object at 0x000001FD7A58EF40>,
                      <__main__.SunSpecModbusClientGroup object at 0x000001FD7A58EEE0>])])
```

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

### Get point value from DERVoltVar model

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Gets the value of the point "Ena" in the "DERVoltVar" model. The output shows the current value is 0.

```python
>>> d.DERVoltVar[0].Ena.value
0
```

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

### SunSpecModbusClientDeviceRTU.__init__

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-client.md

Initializes a new SunSpecModbusClientDeviceRTU instance for Modbus RTU communication.

```APIDOC
## SunSpecModbusClientDeviceRTU.__init__(slave_id, name, baudrate=None, parity=None, timeout=None, ctx=None, trace_func=None, max_count=125, max_write_count=123, model_class=SunSpecModbusClientModel)

### Description
Initializes the device client and registers it with the shared RTU client.

### Parameters
- **slave_id** (int) - Required - Modbus slave id
- **name** (str) - Required - Serial port name (e.g., 'COM2', '/dev/ttyUSB0')
- **baudrate** (int/None) - Optional - Baud rate (default 9600)
- **parity** (str/None) - Optional - 'N' (PARITY_NONE) or 'E' (PARITY_EVEN)
- **timeout** (float/None) - Optional - Request timeout in seconds
- **ctx** (any) - Optional - Not used
- **trace_func** (callable/None) - Optional - Hex trace callback
- **max_count** (int) - Optional - Max count passed to read() (default 125)
- **max_write_count** (int) - Optional - Max count passed to write() (default 123)
- **model_class** (type) - Optional - Model class (default SunSpecModbusClientModel)
```

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

### Get value on point

Source: https://github.com/sunspec/pysunspec2/blob/master/sunspec2/docs/pysunspec.rst

Retrieves the base value of a specific point from a device object.

```python
>>> d.DERMeasureAC[0].LLV.value
2403
```

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

### Get scale factor value on point

Source: https://github.com/sunspec/pysunspec2/blob/master/sunspec2/docs/pysunspec.rst

Retrieves the scale factor associated with a specific point.

```python
>>> d.DERMeasureAC[0].LLV.sf_value
-1
```

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

### Group.__init__

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/group.md

Constructs a Group instance from a group definition and optional wire data, building points and nested groups.

```APIDOC
## Group.__init__

### Description
Constructs a Group instance from a group definition and optional wire data, building points and nested groups.

### Method
Constructor

### Signature
```python
def __init__(self, gdef=None, model=None, model_offset=0, group_len=0, data=None, data_offset=0, group_class=None,
             point_class=None, index=None):
```

### Parameters
- `gdef` (dict) - Optional - Group definition (mdef form); when `None` the group is uninitialized
- `model` (Model) - Optional - Owning model
- `model_offset` (int) - Optional - Register offset of this group within the model
- `group_len` (int) - Optional - Declared group length in registers (from wire/map)
- `data` (bytes/dict/list/None) - Optional - Initial data: bytes are parsed in register order; dict data is indexed by group/point names; list data is indexed for repeating groups
- `data_offset` (int) - Optional - Register offset into byte data
- `group_class` (type) - Optional - Class used for nested groups (defaults to `self.__class__`)
- `point_class` (type) - Optional - Class used for points (defaults to `Point`)
- `index` (int/None) - Optional - 1-based index for repeating group instances (used by `disp`)

### Behavior
Construction builds points and nested groups from `gdef`, tracking `self.points_len` and `self.len` (register counts). Special handling:
- Model 1 "Pad" point: a legacy model-1 definition with group length 65 skips the pad point.
- Repeating groups (gdef has `count`): instantiated via `_init_repeating_group`; stored as a list.
- Length check: if `self.len` is set and `self.len + 2 != mlen` (computed), `model.add_error('Model length %s not equal to calculated model length %s for model %s' ...)` is called (not raised).
- If `self.len > ACCESS_REGION_REGS` (123), access regions are computed with `_init_access` and stored in `self.access_regions` as tuples `(index, count)`.
- An `'L'` point (model length) is set to `self.len - 2`; an `'ID'` point with a pdef `'value'` is set to that value.

### Inherited Attributes
- `gdef`, `model`, `gname` (from `gdef['name']`), `offset`, `len`, `points`, `groups`, `points_len`, `group_class`, `index`, `access_regions`.
```

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

### Run all unit tests with tox

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Runs the unit tests for all supported Python versions using tox.

```sh
tox
```

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

### FileClientModel Constructor

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/file-client.md

Initializes a FileClientModel instance, which handles model definitions and data from a device image.

```python
def __init__(self, model_id=None, model_addr=0, model_len=0, model_def=None, data=None,
             group_class=FileClientGroup, point_class=FileClientPoint):
```

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

### is_impl_string(value)

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/mb.md

Checks if a string is implemented. Returns False when value is falsy or starts with a null character.

```APIDOC
## is_impl_string(value)

### Description
Checks if a string is implemented. Returns False when value is falsy or starts with a null character.

### Parameters
- **value** - Required - Decoded string


### Returns
- **bool** - True if implemented, False otherwise


### Example
```python
if mb.is_impl_string(value): n    pass
```
```

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

### ModelWorkbook.__init__

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/xlsx.md

Initializes a ModelWorkbook instance. If a filename is provided, the workbook is opened read-only; otherwise a new workbook is created with an 'Index' sheet and named styles.

```APIDOC
## ModelWorkbook.__init__

### Description
Initializes a ModelWorkbook instance. If a filename is provided, the workbook is opened read-only; otherwise a new workbook is created with an 'Index' sheet and named styles.

### Method
Constructor

### Signature
python
def __init__(self, filename=None, model_dir=None, license_summary=False, params=None):


### Parameters
- **filename** (str / None) - Optional - Path to an existing workbook; when set the workbook is opened read-only (`openpyxl.load_workbook`) and no new styles are created.
- **model_dir** (str / None) - Optional - Accepted for API compatibility; not used by the implementation.
- **license_summary** (bool) - Optional - Accepted for API compatibility; not used by the implementation.
- **params** (dict / None) - Optional - Styling overrides, see configuration.md.

### Behavior
- If `filename` is `None`, a new workbook is created: the active sheet is titled `'Index'` and ~18 named styles are registered (`suns_hdr`, `suns_group_entry`, `suns_group_entry_1..5`, `suns_group_text_1..5`, `suns_point_entry_1..5`, `suns_point_text_1..5`, `suns_point_variable_entry`, `suns_point_variable_text`, `suns_symbol_entry`, `suns_symbol_text`, `suns_comment`, `suns_entry`, `suns_text`, `suns_hyper`).
- If `openpyxl` is not installed, the constructor raises `ImportError` with message: `'openpyxl library not installed, it is required for working with .xlsx files'`.

### Source
`sunspec2/xlsx.py:80` (full class at lines 79-405 when openpyxl is available; fallback at lines 408-411).
```

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

### SunSpecModbusClientDevice Initialization

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-client.md

Initializes the device with default retry counts and base address probes for SunSpec map discovery.

```python
def __init__(self, model_class=SunSpecModbusClientModel):
    device.Device.__init__(self, model_class=model_class)
    self.did = str(uuid.uuid4())
    self.retry_count = 2
    self.base_addr_list = [40000, 0, 50000]
    self.base_addr = None
```

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

### Validate a model definition

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/mdef.md

Example of calling the validate_model_def function to check a model definition and print any resulting errors.

```python
result = mdef.validate_model_def(model_def)
if result:
    print('definition errors:\n' + result)
```

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

### Point.__init__

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/point.md

Constructor for the Point class. Initializes a point object from a point definition, model, group, and optional data.

```APIDOC
## Point.__init__

### Description
Constructor for the Point class. Initializes a point object from a point definition, model, group, and optional data. If pdef is given, the constructor resolves and stores sf_required, sf_value, info, len, static, standards, and detail.

### Method
Constructor

### Signature
```python
def __init__(self, pdef=None, model=None, group=None, model_offset=0, data=None, data_offset=0):
```

### Parameters
- **pdef** (dict) - Optional - Point definition from the model definition (mdef form); when None the point stays uninitialized
- **model** (Model) - Optional - Containing model object
- **group** (Group) - Optional - Containing group object
- **model_offset** (int) - Optional - Modbus register offset of this point from the start of the model
- **data** (bytes/bytearray/dict/None) - Optional - Initial data; when present, values are parsed via _set_data()
- **data_offset** (int) - Optional - Register offset into data (bytes offset = data_offset * 2)

### Attributes Set
- **sf_required** (bool) - True if pdef has sf
- **sf_value** (int) - Literal integer scale factor if sf is a literal; otherwise sf holds the name of a sunssf point
- **info** (mb.PointInfo) - The PointInfo entry for the point type
- **len** (int) - Register length (from pdef['size'] if present, else info.len)
- **static** (bool) - True when pdef has 'static': 'S'
- **standards** - Copied from pdef when present
- **detail** - Copied from pdef when present
- **model** - Containing model object
- **group** - Containing group object
- **pdef** - Point definition
- **offset** - Register offset
- **_value** - Raw register value (default None)
- **dirty** (bool) - Dirty flag (default False)
- **sf** - Scale factor
- **read_func** / **read_func_arg** - Read function and argument
- **write_func** / **write_func_arg** - Write function and argument
```

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

### computeCRC(data)

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-modbus.md

Computes the CRC-16 (Modbus variant with start 0xffff) of the given data bytes. Returns an integer.

```APIDOC
## computeCRC(data)

### Description
Computes the CRC-16 (Modbus variant with start 0xffff) of the given data bytes. Returns an integer.

### Parameters
- **data** (bytes) - Required - Input data for CRC computation.

### Returns
- **int** - CRC-16 value.

### Source
`sunspec2/modbus/modbus.py:122-147`
```

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

### ModbusClientRTU.__init__(name, baudrate, parity, timeout)

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-modbus.md

Constructs a Modbus RTU client. Opens the serial port immediately and computes the inter-frame gap from the baud rate.

```APIDOC
## ModbusClientRTU.__init__(name, baudrate, parity, timeout)

### Description
Constructs a Modbus RTU client. Opens the serial port immediately and computes the inter-frame gap from the baud rate.

### Parameters
- **name** (str) - Optional - Serial port name. Default: '/dev/ttyUSB0'.
- **baudrate** (int) - Optional - Baud rate. Default: 9600.
- **parity** (str or None) - Optional - Parity setting: 'N' or 'E'. Default: None.
- **timeout** (float) - Optional - Read and write timeout in seconds. Default: 0.5.

### Attributes
- **name** - Serial port name.
- **baudrate** - Baud rate.
- **parity** - Parity setting.
- **serial** - pyserial Serial or None.
- **timeout** - Timeout.
- **write_timeout** - Write time out.
- **devices** - Dictionary mapping slave_id to device.
- **trace_func** - Trace function (None).
- **inter_frame_gap** - Inter-frame gap.

### Source
`sunspec2/modbus/modbus.py:149`
```

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

### is_impl_ipv6addr(value)

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/mb.md

Checks if an IPv6 address is implemented. Returns False when value is falsy or starts with a null character.

```APIDOC
## is_impl_ipv6addr(value)

### Description
Checks if an IPv6 address is implemented. Returns False when value is falsy or starts with a null character.

### Parameters
- **value** - Required - Decoded IPv6 address


### Returns
- **bool** - True if implemented, False otherwise


### Example
```python
if mb.is_impl_ipv6addr(value): n    pass
```
```

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

### SunSpecModbusClientModel Constructor

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-client.md

Initializes a new SunSpecModbusClientModel instance with optional model parameters and device configuration.

```python
def __init__(self, model_id=None, model_addr=0, model_len=0, model_def=None, data=None, mb_device=None,
             group_class=SunSpecModbusClientGroup, point_class=SunSpecModbusClientPoint):
```

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

### SunSpecModbusClientModel

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/modbus-client.md

Documentation for the SunSpecModbusClientModel class constructor and its methods.

```APIDOC
## SunSpecModbusClientModel.__init__

### Description
Initializes a SunSpec Modbus client model. Loads the model definition, optionally reads missing tail registers from the owning device, and validates the model length.

### Method
Constructor

### Signature
```python
def __init__(self, model_id=None, model_addr=0, model_len=0, model_def=None, data=None, mb_device=None,
             group_class=SunSpecModbusClientGroup, point_class=SunSpecModbusClientPoint)
```

### Parameters
- **model_id** (`int` / `None`) - Optional - Model id
- **model_addr** (`int`) - Optional - Register address of the model start
- **model_len** (`int`) - Optional - Model length in registers (from map)
- **model_def** (`dict` / `None`) - Optional - Definition; loaded via `device.get_model_def` when `None`
- **data** (`bytes` / `None`) - Optional - Initial register bytes (from scan)
- **mb_device** (`SunSpecModbusClientDevice`) - Optional - Owning device (read/write target)
- **group_class** (`type`) - Optional - Nested group class
- **point_class** (`type`) - Optional - Point class

### Behavior
- Records definition load errors with `add_error`.
- Computes `group_len_points_index = mdef.get_group_len_points_index(gdef)`; if the provided `data` is shorter than that index (in registers), reads the missing tail registers from `mb_device`: `points_data = self.device.read(self.model_addr + data_regs, remaining); data += points_data`.
- After `Group.__init__`, sets `self.len = model_len` when `model_len is not None`, and calls `add_error('Model error: Discovered length %s does not match computed length %s' ...)` if `model_len` and computed `self.len` differ.

## SunSpecModbusClientModel.add_error

### Description
Appends an error message to the model's error information.

### Method
Method

### Signature
```python
def add_error(self, error_info)
```

### Parameters
- **error_info** - The error message to append.

### Behavior
Appends `'%s\n'` to `error_info`.

## SunSpecModbusClientModel.read

### Description
Reads the full model including its `ID`/`L` header registers.

### Method
Method

### Signature
```python
def read(self, len=None)
```

### Parameters
- **len** - Optional - Length to read; defaults to `self.len + 2`.

### Behavior
Calls `SunSpecModbusClientGroup.read(self, len=self.len + 2)`.
```

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

### Catching ModelError

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/errors.md

Shows how to catch ModelError when performing object-model operations. The example creates a Model with model_id=705 and attempts to read a point, which may raise ModelError.

```python
from sunspec2.device import ModelError, Model
try:
    m = Model(model_id=705)
    m.Crv[0].read()   # or any ModelError-raising operation
except ModelError as e:
    print('model error:', e)
```

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

### Initialize device and scan

Source: https://github.com/sunspec/pysunspec2/blob/master/README.rst

Initializes a SunSpec Modbus client device for RTU communication with slave_id 1 on COM2, and runs device discovery with scan().

```python
>>> d = client.SunSpecModbusClientDeviceRTU(slave_id=1, name="COM2")
>>> d.scan()
```

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

### get_value(self, computed=False)

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/point.md

Reads the point value. If a read_func is installed, it is invoked first. When computed=True and a scale factor exists, the value is scaled using the scale factor.

```APIDOC
## get_value(self, computed=False)

### Description
Reads the point value. If a read_func is installed, it is invoked first. When computed=True and a scale factor exists, the value is scaled using the scale factor.

### Method
Python method

### Signature
`get_value(self, computed=False)`

### Parameters
- **computed** (bool) - Optional, default False - Apply scale factor and return computed value

### Behavior
- If a read_func is installed, it is invoked first (`self.read_func(self.model, self.read_func_arg)`).
- When computed=True and the point has a scale factor: if sf_value is unknown and the factor is a named sunssf point (not a literal), it is looked up in group.points then model.points.
- Result: `round(v * math.pow(10, sfv), -1 * sfv)` when sf_value truthy.

### Errors
- Throws `ModelError('Scale factor %s for point %s not found' ...)` when a named scale factor point cannot be resolved.
```

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

### ModelWorkbook constructor stub raising ImportError when openpyxl is missing

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/xlsx.md

Defines the ModelWorkbook class with a constructor that immediately raises ImportError if openpyxl is not installed. This is the fallback when the optional 'excel' extra is not present.

```python
class ModelWorkbook(object):
    def __init__(self, filename=None, model_dir=None, license_summary=False):
        raise ImportError('openpyxl library not installed, it is required for working with .xlsx files')
```

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

### Device.get_dict

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/device.md

Serializes the device and its models into a dictionary representation.

```APIDOC
## Device.get_dict

### Description
Converts the device state into a dictionary containing the device name, ID, and a list of model dictionaries.

### Parameters
- **computed** (bool) - Optional - If true, point values are returned as computed values. Defaults to False.

### Returns
dict - A dictionary with keys 'name', 'did', and 'models'.
```

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

### Set computed value on a point with scale factor -1

Source: https://github.com/sunspec/pysunspec2/blob/master/sunspec2/docs/pysunspec.rst

Sets the computed value (cvalue) of a point, where the computed value is calculated from the scale factor (-1). The example sets ESVHi to 245.1.

```python
>>> d.DEREnterService[0].ESVHi.cvalue = 245.1
```

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

### set_info(self, ws, row, values, style=None)

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/xlsx.md

Writes label, description, and notes cells for a spreadsheet row.

```APIDOC
## set_info(self, ws, row, values, style=None)

### Description
Writes `Label`, `Description`, and (when present) `Notes` cells for a spreadsheet row.

### Method
N/A (Python method)

### Parameters
- `ws` (worksheet) - Required - The worksheet.
- `row` (int) - Required - Row number.
- `values` (list) - Required - Values for the row.
- `style` (optional) - Optional - Style to apply.

### Returns
None

```

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

### from_smdx_file(filename)

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/smdx.md

Parses an SMDX XML file and returns a model definition dictionary.

```APIDOC
## from_smdx_file(filename)

### Description
Parses an SMDX XML file and returns a model definition dictionary. Raises `ET.ParseError` for malformed XML and `mdef.ModelDefinitionError` for schema violations.

### Parameters
- **filename** (str) - Required - Path to an SMDX `.xml` file.

### Returns
- **dict** - A model definition dictionary with keys `id` (int) and `group` (dict).

### Raises
- **ET.ParseError** - If the XML is malformed.
- **mdef.ModelDefinitionError** - If the XML does not conform to the SMDX schema.
```

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

### Device.get_json

Source: https://github.com/sunspec/pysunspec2/blob/master/_autodocs/api-reference/device.md

Serializes the device into a JSON string.

```APIDOC
## Device.get_json

### Description
Returns a JSON string representation of the device by serializing the output of get_dict.

### Parameters
- **computed** (bool) - Optional - If true, point values are returned as computed values. Defaults to False.

### Returns
str - JSON string representation of the device.
```
Tokens:
Raw