API Reference¶

`sunspec.core` — SunSpec Core Functionality¶

The core package contains modules that provide the ability to interact with SunSpec devices and encode/decode documents in SunSpec standard formats. The modules in the core package used to interact with SunSpec devices are organized into the following main functional areas: base SunSpec device/model support, Modbus protocol support, and client device support.

The device module provides objects that map to the SunSpec model definitions within the SunSpec standards. A device is a collection of SunSpec model definitions that are implemented by a SunSpec compliant device. The device module provides objects for device, model, block, and point instances as well as objects that support the model, block, and point type definitions.

The modbus package provides protocol support for Modbus TCP, Modbus RTU, and locally defined Modbus maps that can be accessed directly.

The client module extends the basic objects in the device module to provide objects that can be used to access devices using the Modbus protocol objects supplied in the modbus package.

`sunspec.core.client` — SunSpec Client classes¶

Classes¶

Exceptions¶

exception sunspec.core.client.SunSpecClientError¶: Derived from sunspec.core.device.SunSpecError. Raised for any sunspec module error in sunspec.core.client classes.

Constants¶

Device Types

sunspec.core.client.RTU¶

sunspec.core.client.TCP¶

sunspec.core.client.MAPPED¶

RTU Device Parity

sunspec.core.client.PARITY_NONE¶

sunspec.core.client.PARITY_EVEN¶

`sunspec.core.device` — SunSpec Device classes¶

The device module provides the base SunSpec device functionality. A SunSpec device consists of a set of SunSpec models which contain blocks and points as specified in the respective SunSpec model definitions.

Classes¶

class sunspec.core.device.Device(addr=40000)¶

Parameters:	addr – Modbus base address of device.
Raises:	`SunSpecError` – Any error encountered in device processing.

base_addr¶: Modbus base address of the device.

models_list¶: List of model objects present in the device in the order in which they appear in the device.

models¶: Dictionary of model object lists reperesenting model types present in the device indexed by model id. The elements are model lists to allow more than one model of the same model type to be present in the device.

add_model(model)¶

Add a model object to the device.

Parameters:	model – Model object to add to the device.

from_pics(element=None, filename=None, pathlist=None)¶

The PICS information for the device can be either an Element Tree element for a device from a document already being processed or the file name of document in the file system. Populates the device based on the elements within the device element.

Parameters:	element – Element Tree device element. filename – File name of the PICS document. pathlist – Pathlist object containing alternate paths to the PICS document.

to_pics(parent, single_repeating=True)¶

Adds the device and all elements within the device to the parent element. If single_repeating is True, only the first repeating block for each model is added to the document.

Parameters:	parent – Element Tree element on which to place the device element. single_repeating – Flag to indicate whether to include a single or all repeating blocks within each model in the PICS document.

not_equal(device)¶

Determines if the specified device instance is not equal based on all the device attribute values including models, blocks and points. If not equal, returns a string indicating why the device is not equal. Returns False if the device is equal.

Parameters:	device – Device to compare.

class sunspec.core.device.Model(device=None, mid=None, addr=0, mlen=0, index=1)¶

Parameters:	device – Device associated with the model. mid – Model id. addr – Modbus address of the first point in the model. mlen – Length of the model in Modbus registers. index – Model instance index for the model type within the device.
Raises:	`SunSpecError` – Any error encountered in device processing.

device¶: Device instance that contains the model instance.

id¶: Model id. The model id maps to a SunSpec model type definition.

index¶: Model instance index for the model type within the device. Model instance indexes start at 1 for the first model type instance.

model_type¶: The sunspec.core.device.ModelType instance associated with the model.

addr¶: Modbus address of the first point in the model.

len¶: Length of the model in Modbus registers.

points_list¶: List of fixed block non-scale factor points ordered by offset.

points¶: Dictionary of fixed block non-scale factor points indexed by point id.

points_sf¶: Dictionary of fixed block scale factor points indexed by point id.

blocks¶: List of blocks contained in the model instance. Block 0 is the fixed block if present and blocks 1 to n are the repeating block instances.

load(block_class=<class 'sunspec.core.device.Block'>, point_class=<class 'sunspec.core.device.Point'>)¶

Loads the model instance with blocks and points based on the SunSpec model type definition.

Parameters:	block_class – Block class to use to create block instances. point_class – Point class to use to create point instances.

from_pics(element)¶

Sets the model contents based on an element tree model type element contained in a SunSpec PICS document.

Parameters:	element – Element Tree model element.

to_pics(parent, single_repeating=True)¶

Adds the model and all elements within the model to the parent element. If single_repeating is True, only the first repeating block is added to the document.

Parameters:	parent – Element Tree element on which to place the model element. single_repeating – Flag to indicate whether to include a single or all repeating blocks within the model in the PICS document.

not_equal(model)¶

Determines if the specified model instance is not equal based on all the model attribute values including blocks and points. If not equal, returns a string indicating why the model is not equal. Returns False if the model is equal.

Parameters:	device – Model to compare.

class sunspec.core.device.Block(model, addr, blen, block_type, index=1)¶

Parameters:	model – Model associated with the block. addr – Modbus address of the first point in the block. blen – Length of the block in Modbus registers. block_type – The `sunspec.core.device.BlockType` instance associated with the block. index – Block instance index for the block type within the model.

model¶: Model associated with the block.

block_type¶: The sunspec.core.device.BlockType instance associated with the block.

addr¶: Modbus address of the first point in the block.

len¶: Length of the block in Modbus registers.

type¶: Block type, either sunspec.core.suns.SUNS_BLOCK_FIXED or sunspec.core.suns.SUNS_BLOCK_REPEATING.

index¶: Block instance index for the block type within the model.

points_list¶: List of non-scale factor points in the block ordered by offset.

points¶: Dictionary of non-scale factor points in the block indexed by point id.

points_sf¶: Dictionary of scale factor points int the block indexed by point id.

from_pics(element)¶

Sets the block contents based on an element tree model type element contained in a SunSpec PICS document.

Parameters:	element – Element Tree model element.

to_pics(parent)¶

Adds the block and all elements within the block to the parent element.

Parameters:	parent – Element Tree element on which to place the block element.

not_equal(block)¶

Determines if the specified block instance is not equal based on all the block attribute values including points. If not equal, returns a string indicating why the block is not equal. Returns False if the block is equal.

Parameters:	device – Block to compare.

class sunspec.core.device.Point(block=None, point_type=None, addr=None, sf_point=None, value=None)¶

Parameters:	block – Block associated with the point. point_type – The `sunspec.core.device.PointType` instance associated with the point. addr – The Modbus address of the point. sf_point – Scale factor point associated with the point if present. value – Initial value for the value_base attribute of the point.

block¶: Block associated with the point.

point_type¶: The sunspec.core.device.PointType instance associated with the point.

addr¶: Modbus address of the point.

sf_point¶: Scale factor point associated with the point if present.

impl¶: Indication if the point is implemented. A value of True indicates the point is implmented. Intended to be used for cases when no initial value is given for the point but the implementation status is known as in SunSpec PICS documents.

value_base¶: Value of the point without the point scale factor applied.

value_sf¶: Scale factor point value.

dirty¶: Indication if the point has been written to the physical device since the last update of the point. A value of True indicates that the point has not been written since the last update.

value¶: Value of the point with the scale factor applied.

from_pics(element)¶

Sets the block contents based on an element tree model type element contained in a SunSpec PICS document.

Parameters:	element – Element Tree model element.

to_pics(parent)¶

Adds the point to the parent element.

Parameters:	parent – Element Tree element on which to place the point element.

not_equal(point)¶

Determines if the specified point instance is not equal based on all the point attribute values. If not equal, returns a string indicating why the point is not equal. Returns False if the point is equal.

Parameters:	device – Point to compare.

class sunspec.core.device.ModelType(mid=None)¶

Parameters:	mid – Model id that identifies a specific SunSpec model type definition.

id¶: Model id that identifies a specific SunSpec model type definition.

len¶: Length in Modbus registers of the model type as specified in the model definition.

label¶: Label string as specified in the model definition.

description¶: Description string as specified in the model definition.

notes¶: Notes string as specified in the model definition.

fixed_block¶: Fixed block type as specified in the model definition if present.

repeating_block¶: Repeating block type as specified in the model definition if present.

from_smdx(element)¶

Sets the model type attributes based on an element tree model type element contained in an SMDX model definition.

Parameters:	element – Element Tree model type element.

not_equal(model_type)¶

Determines if the specified model type instance is not equal based on all the model type attribute values including blocks and points. If not equal, returns a string indicating why the model type is not equal. Returns False if the model type is equal.

Parameters:	model_type – Model type to compare.

class sunspec.core.device.BlockType(btype=None, blen=0, name=None, model_type=None)¶

Parameters:	btype – Block type as specified in the model definition. Valid values are sunspec.core.suns.SUNS_BLOCK_FIXED or sunspec.core.suns.SUNS_BLOCK_REPEATING. blen – Block length in Modbus registers.

type¶: Block type as specified in the model definition. Valid values are sunspec.core.suns.SUNS_BLOCK_FIXED or sunspec.core.suns.SUNS_BLOCK_REPEATING.

len¶: Block length in Modbus registers.

points_list¶: List containing the points in the block in offset order.

points¶: Dictionary containg the points in the block indexed by the point id.

from_smdx(element)¶

Sets the block type attributes based on an element tree block type element contained in an SMDX model definition.

Parameters:	element – Element Tree block type element.

not_equal(block_type)¶

Determines if the specified block type instance is not equal based on all the block type attribute values including points. If not equal, returns a string indicating why the block type is not equal. Returns False if the block type is equal.

Parameters:	block_type – Block type to compare.

class sunspec.core.device.PointType(pid=None, offset=None, ptype=None, plen=None, mandatory=None, access=None, sf=None, block_type=None)¶

Parameters:

pid – Point id as specified in the model definition.
offset – Point offset within the block as specified in the model definition.
ptype – Point type as specified in the model definition. Valid values are defined in sunspec.core.suns.SUNS_TYPE_*.
plen – Point length in Modbus registers for points that have a type of ‘string’.
mandatory – Mandatory indication as specified in the model definition. Valid values are sunspec.core.suns.SUNS_MANDATORY_TRUE or sunspec.core.suns.SUNS_MANDATORY_FALSE.
access – Point access setting as specfied in the model definition. Valid values are sunspec.core.suns.SUNS_ACCESS_R or sunspec.core.suns.SUNS_ACCESS_RW.
sf – Id of the scale factor point associated with the point or None if the point does not have a scale factor.

id¶: Point id as specified in the model definition.

offset¶: Point offset within the block as specified in the model definition.

type¶: Point type as specified in the model definition. Valid values are defined in sunspec.core.suns.SUNS_TYPE_*.

len¶: Point length in Modbus registers for points that have a type of ‘string’.

mandatory¶: Mandatory indication as specified in the model definition. Valid values are sunspec.core.suns.SUNS_MANDATORY_TRUE or sunspec.core.suns.SUNS_MANDATORY_FALSE.

access¶: Point access setting as specfied in the model definition. Valid values are sunspec.core.suns.SUNS_ACCESS_R or sunspec.core.suns.SUNS_ACCESS_RW.

sf¶: Id of the scale factor point associated with the point or None if the point does not have a scale factor.

label¶: Label string as specified in the model definition.

description¶: Description string as specified in the model definition.

notes¶: Notes string as specified in the model definition.

value_default¶: Default value for a point instance if no value specified.

is_impl¶: Contains the function to call with the point value as an argument to determine if the point is implemented.

data_to¶: Contains the function to call to transform a binary data string to the point value.

to_data¶: Contains the function to call to transform the point value to a binary data string.

to_value¶: Contains the function to call to transform a point value string into a point value of the type associated with the point.

from_smdx(element, strings=False)¶

Sets the point attributes based on an element tree point element contained in an SMDX model definition.

Parameters:	element – Element Tree point type element. strings – Indicates if element is a subelement of the ‘strings’ definintion within the model definition.

not_equal(point_type)¶

Determines if the specified point type instance is not equal based on all the point type attribute values. If not equal, returns string indicating why the point type is not equal. Returns False if the point type is equal.

Parameters:	point_type – Point type to compare.

Exceptions¶

exception sunspec.core.device.SunSpecError¶: Raised for sunspec.core.device errors.

`sunspec.core.modbus` — SunSpec Modbus Package¶

The Modbus package provides standard Modbus support for Modbus RTU, Modbus TCP, and Modbus file mapped client devices.

`sunspec.core.modbus.client` — Modbus Client classes¶

Classes¶

Exceptions¶

exception sunspec.core.modbus.client.ModbusClientError¶: Raised for general errors in sunspec.core.modbus.client modules.

exception sunspec.core.modbus.client.ModbusClientTimeout¶: Raised for Modbus timeout errors. Derived from ModbusClientError.

exception sunspec.core.modbus.client.ModbusClientException¶: Raised for Modbus protocol exceptions. Derived from ModbusClientError.

Constants¶

Parity

sunspec.core.modbus.client.PARITY_NONE¶

sunspec.core.modbus.client.PARITY_EVEN¶

Read Modbus Functions

sunspec.core.modbus.client.FUNC_READ_HOLDING¶

sunspec.core.modbus.client.FUNC_READ_INPUT¶

`sunspec.core.modbus.mbmap` — Modbus Map classes¶

The mbmap module implements a local Modbus map image. The map supports read and write operations and can be used by Modbus clients in place of an actual modbus device. The module supports an xml encoding for representing modbus maps as a document.

The xml representation has a root element of mbmap that contains a set of regs elements representing one or more registers in the map. Currently only big endian is supported.

Attributes for mbmap element:

Attribute	Description	Valid values	Default value
addr	Base Modbus address	Valid modbus address	40000
func	Modbus function associated with the map	holding, input	holding

Attributes for regs element:

Attribute	Description	Valid values	Default value
offset	Register offset	Value with map length	Next offset
type	Register(s) type	s16, u16, s32, u32, s64, u64, f32, f64, string, hexstr	hexstr
len	String length for string type	Value within map length	Length of the regs element value

If the registers are contiguous, offset is optional.

The hexstr type is a series of ascii hex characters. Spaces are removed from the string before processing and can be used to increase readability.

Example:

<mbmap>
  <!-- common model -->
  <regs type="string" len="2">SunS</regs>
  <regs type="u16">1</regs>
  <regs type="u16">66</regs>
  <regs type="string" len="16">SunSpecTest</regs>
  <regs type="string" len="16">TestInverter-1</regs>
  <regs type="string" len="8">opt_a_b_c</regs>
  <regs type="string" len="8">1.2.3</regs>
  <regs type="string" len="16">sn-123456789</regs>
  <regs type="u16">1</regs>
  <regs type="u16">0</regs>

  <!-- short test model -->
  <regs type="u16">63010</regs>
  <regs type="u16">4</regs>

  <!-- example of hexstr -->
  <regs>00 79 00 1E</regs>
  <regs>0079 001E</regs>

  <!-- end of models -->
  <regs type="u16">0xffff</regs>
  <regs type="u16">0</regs>
</mbmap>

Classes¶

class sunspec.core.modbus.mbmap.ModbusMap(slave_id=None, func='holding', base_addr=40000, ns=None, lid=None, mapid=None, time=None)¶

Parameters:	slave_id – Modbus slave id. func – Modbus function string associated with the map. Valid values are: `sunspec.core.modbus.mbmap.MBMAP_FUNC_HOLDING` or `sunspec.core.modbus.mbmap.MBMAP_FUNC_INPUT`. base_addr – Base address of the Modbus map.
Raises:	`ModbusMapError` – Raised for any modbus map error.

slave_id¶: Modbus slave id.

func¶: Actual Modbus function associated with the map.

base_addr¶: Base address of the Modbus map.

regs¶: List of sunspec.core.modbus.mbmap.ModbusMapRegs blocks that comprise the Modbus register map.

from_xml(filename=None, pathlist=None, element=None)¶

Load Modbus map from a Modbus map (mbmap) formatted file.

Parameters:	filename – File name of the Modbus map file pathlist – Pathlist object containing alternate paths to the Modbus map file.

read(addr, count, op=None)¶

Read Modbus map registers.

Parameters:	addr – Starting Modbus address. count – Read length in Modbus registers.
Returns:	Byte string containing register contents.

write(addr, data)¶

Write Modbus map registers.

Parameters:	addr – Starting Modbus address. count – Byte string containing register contents.

not_equal(mbmap)¶: Determines if the specified modbus map instance is not equal based on the content of the map. If not equal, returns a string indicating why the map is not equal. Returns False if the map is equal.

class sunspec.core.modbus.mbmap.ModbusMapRegs(offset, count, data, access='r')¶

Parameters:	offset – Register offset into Modbus map. count – Register count. data – Byte string containing register data. access – Access for the register block. Valid values are: `sunspec.core.modbus.mbmap.MBMAP_REGS_ACCESS_R` and `sunspec.core.modbus.mbmap.MBMAP_REGS_ACCESS_RW`.
Raises:	exception ModbusMapError: Raised for any modbus map error.

offset¶: Start register offset of the register block.

count¶: Register count in the block.

data¶: Byte string containing data in the register block.

access¶: Access setting for the block. The access setting is currently not enforced.

read(offset, count)¶

Read Modbus map registers in register block.

Parameters:	offset – Register offset into Modbus map. count – Register count.
Returns:	Byte string containing register contents.

write(offset, data)¶

Write Modbus map registers tp register block.

Parameters:	addr – Register offset into Modbus map. count – Byte string containing register contents.

append(offset, count, data, access='r')¶

Append registers to end of register block.

Parameters:	offset – Register offset into Modbus map. count – Register count. data – Byte string containing register data. access – Access for the register block. Valid values are: `sunspec.core.modbus.mbmap.MBMAP_REGS_ACCESS_R` and `sunspec.core.modbus.mbmap.MBMAP_REGS_ACCESS_RW`.

not_equal(regs)¶: Determines if the specified modbus map block instance is not equal based on the content of the map block. If not equal, returns a string indicating why the map block is not equal. Returns False if the map block is equal.

Exceptions¶

exception sunspec.core.modbus.mbmap.ModbusMapError¶: Raised for errors in sunspec.core.modbus.mbmap modules.

Constants¶

Modbus Map Functions

sunspec.core.modbus.mbmap.MBMAP_FUNC_INPUT¶

sunspec.core.modbus.mbmap.MBMAP_FUNC_HOLDING¶

API Reference¶

sunspec.core — SunSpec Core Functionality¶

sunspec.core.client — SunSpec Client classes¶

Classes¶

Exceptions¶

Constants¶

sunspec.core.device — SunSpec Device classes¶

Classes¶

Exceptions¶

sunspec.core.modbus — SunSpec Modbus Package¶

sunspec.core.modbus.client — Modbus Client classes¶

Classes¶

Exceptions¶

Constants¶

sunspec.core.modbus.mbmap — Modbus Map classes¶

Classes¶

Exceptions¶

Constants¶

`sunspec.core` — SunSpec Core Functionality¶

`sunspec.core.client` — SunSpec Client classes¶

`sunspec.core.device` — SunSpec Device classes¶

`sunspec.core.modbus` — SunSpec Modbus Package¶

`sunspec.core.modbus.client` — Modbus Client classes¶

`sunspec.core.modbus.mbmap` — Modbus Map classes¶