Over Serial Configuration - Sketch 4

Overview

This page covers version 4.x.x of the sketch. See appropriate documentation for other version.

RPICT board using Atmega microcontrollers can be configured over serial using a utility written in python.
This involves boards RPICT7V1 RPICT4V3 and RPICT8 RPICT4W3T1 RPIZ_CT4V3T2.

Current version allows changes of

• Device id
• Polling (polling interval of data)
• Ical (current calibration value)
• Vcal (Voltage calibration value)
• Phasecal
• Vest (estimated voltage for power estimate)
• Expected Frequency
• List of CV pairs to compute.
• List of channels to output.

Limitations

Maximum Channels

The maximum number of channels is not known at time of writing. This depends on a number of factor and mainly the configuration size and type of nodes used.

If limits are encountered when using numerous number of nodes and channels we recommend to opt for hardcoded configuration.

Minimum Polling

We should not poll data more often that it can complete a full scan cycle. Minimum polling will depend on the number of CV pairs to compute and the length of the sampling window.

As a rule of thumb one should expect each CV pair to take 0.2 seconds (10 cycles being computed).

Download

You can download the hex file directly onto the Raspberrypi using the command below.

wget lechacal.com/RPICT/sketch/RPICT_MCP3208_v4.0.2.ino.hex

The source code is available in the link below.
http://lechacal.com/RPICT/sketch/RPICT_MCP3208_v4.0.2.ino

RPICT Configuration tool

The configuration tool is a Python program called lcl-rpict-config.py.

Installation

The configuration tool is part of the lcl-rpict-package package. This is installed using the commands below.

wget lechacal.com/RPICT/tools/lcl-rpict-package_latest.deb
sudo dpkg -i lcl-rpict-package_latest.deb

Reading current configuration

Running the configurator like this below only reads the configuration stored in the board.

lcl-rpict-config.py -a

This yields

# RPICT Configuration Utility
# Read only
# Now reset RPICT hardware

Once the board receives the reset the configuration will be partially shown and saved in /tmp/rpict.conf. If you have entered the -a option the reset will be performed automatically.

# 
# Configuration in memory:
# 
# Structure: 0xb5
# Format: 3
# device_id: 11
# output_rate: 5000
# KCAL:  635.0 635.0 635.0 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469   83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469  83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469
# PHASECAL: 0
# VEST: 240.000000
# xpFREQ: 50
# Ncycle: 20
# N signal node: 1
# N power node: 3
# N 3p node: 0
# N freq node: 0
# N channels: 6
# debug: 0
# model:  0 2 0 0 0 0
# Config from MCU fully sent
#

Every time the configuration is read from the board it stores a copy in the /tmp/rpict.conf file. Save this file somewhere safe before you attempt to change anything. This can be used to restore the config.

Modify the configuration

To change the values the configurator must be fed with a file containing the new values. We will use the example of a RPICT4V3. Such file contains this below.

[main]
format = 3
device_id = 11
output_rate = 5000
kcal = 635.0 635.0 635.0 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469 83.33000183105469
phasecal = 0
vest = 240.000000
xpFREQ = 50
Ncycle = 20
debug = 0
model = 0 2 0 0 0 0
snode_pin = 4
snode_mcp = 10
pnode_pinI = 7 6 5
pnode_mcpI = 10 10 10
pnode_pinV = 2 1 0
pnode_mcpV = 10 10 10
tnode_pinI =
tnode_mcpI =
tnode_pinV =
tnode_mcpV =
fnode_pin =
fnode_mcp =
CHID = 0 1 2 0 1 2
CH_node_type = 3 3 3 3 3 3
CH_field_type = 1 1 1 3 3 3

Manual Edit

The above file can be opened in a text file and edited manually. All the parameters are explained in details down below this same page.

One can modify the file manually and save it in a file called my_file.conf (for example). Then we can now start the configurator with the -w option to write it to the device.

$ lcl-rpict-config.py -a -w my_file.conf

After the reset the configurator will read the old config then write the new config and display the newly stored once again.

Webtool Edit

To build and edit this file there is an online configurator.

This runs on the Raspberrypi and is already installed with the lcl-rpict-package package.

Simply run from a terminal

lcl-server.sh

Then access the webtool from any browser using the address below

http://raspberrypi:8000

You might have to replace raspberrypi with the ip address of the raspberrypi. Or if you are accessing from the Desktop of the raspberrypi itself just use.

http://127.0.0.1:8000

More about the web tool is explained in this guide below.
RPICT configuration web tool

The configuration file

We will explain here the meaning of each parameters of the configuration file introduced above.

Table 0: Parameters

Parameter	Description	Data type	Expected Range	Default Value
format	format output to be used by the serial port.	uint8_t	3 - Space Separated Values	3
nodeid	Device identification number. Well used with emonhub format.	uint8_t	Any number between 0 and 255.	11
output_rate	Number of milliseconds between each data to be sent over serial.	uint16_t	Any non null number up to 65535.	5000
kcal	Current or Voltage calibration coefficient. Formerly Ical or Vcal. Must contain 5 times 8 values. The first 8 values are for master. The second 8 values are for slave1 etc.. Each values inside a block of 8 must be in the same order as in Table 1 below. The example above shows for a rpict4v3 vcal=635 then all ical=83.33.	float[5][8]	Any floating point number.	Depends on board type.
phasecal	Phase Calibration value. Adjust phase delay between Voltage and Current. 0 is usually the best option unless tests prove otherwise.	int8_t	An integer between -9 and +9.	0
vest	Voltage to compute estimated power. Usually 240V 230V or 120V. Only applies for channel type number 5 (estimated power). Must be set even if not used. Set vest=1 to obtain output as ampere instead of watts. Set vest=1000 to get milliampere. RPICT boards with a voltage port are not using this parameter.	float	Any floating point number.	240.0
xpFREQ	Expected Frequency. The expected frequency dominating the signal to measure should be set here. Typically 50 or 60Hz. This does not have to be highly accurate. A nominal value usually suffice.	uint8_t	An integer between 1 and 255	50
Ncycle	Set the number of cycle to measure. This directly set the sampling window. Minimum would be 1. Maximum 255. The lower the number the faster and more responsive are the data but more prone to anomalies. The higher the number the slower the reading but more averaged over time. Values between 5 and 20 are usually good.	uint8_t	An integer between 1 and 255	20
debug	Turn debug on/off	uint8_t	0 - OFF 1 - ON	0
model	Defined the models used on each stack level. This is particularly used by the sketch but rather for the web tool. First value if the number of slaves in the stack. Then each value are the model ID for master/slave1/slave2/slave3/slave4. Models ID are shown in the table down this page.	uint8_t	A list of 6 integers between 1 and 255	0 2 0 0 0 0
snode_pin	Signal Node. Channel definition. Values between 0 and 7. See Table 1 below.	uint8_t[]	A list of integer between 0 and 7	Depends on board type.
snode_mcp	Signal Node. Stack level definition. Values between 6 and 10. See Table 2 below.	uint8_t[]	A list of integer between 6 and 10.	Depends on board type.
pnode_pinI	Power Node. Channel definition for current field. Values between 0 and 7. See Table 1 below.	uint8_t[]	A list of integer between 0 and 7.	Depends on board type.
pnode_mcpI	Power Node. Stack level definition for current field. Values between 6 and 10. See Table 2 below.	uint8_t[]	A list of integer between 6 and 10.	Depends on board type.
pnode_pinV	Power Node. Channel definition for voltage field. Values between 0 and 7. See Table 1 below.	uint8_t[]	A list of integer between 0 and 7.	Depends on board type.
pnode_mcpV	Power Node. Stack level definition for voltage field. Values between 6 and 10. See Table 2 below.	uint8_t[]	A list of integer between 6 and 10.	Depends on board type.
tnode_pinI	Three Phase Node. Channel definition for current field. Values between 0 and 7. See Table 1 below.	uint8_t[]	A list of integer between 0 and 7.	Depends on board type.
tnode_mcpI	Three Phase Node. Stack level definition for current field. Values between 6 and 10. See Table 2 below.	uint8_t[]	A list of integer between 6 and 10.	Depends on board type.
tnode_pinV	Three Phase Node. Channel definition for voltage field. Values between 0 and 7. See Table 1 below.	uint8_t[]	A list of integer between 0 and 7.	Depends on board type.
tnode_mcpV	Three Phase Node. Stack level definition for voltage field. Values between 6 and 10. See Table 2 below.	uint8_t[]	A list of integer between 6 and 10.	Depends on board type.
fnode_pin	Frequency Node. Channel definition. Values between 0 and 7. See Table 1 below.	uint8_t[]	A list of integer between 0 and 7	Depends on board type.
fnode_mcp	Frequency Node. Stack level definition. Values between 6 and 10. See Table 2 below.	uint8_t[]	A list of integer between 6 and 10.	Depends on board type.
CHID	Node index within the nodes defined above. 0 being the first node or either snode/pnode/tnode/fnode.	uint8_t[]	A list of integers between 0 and 255	Depends on board type.
CH_node_type	Type of node selecting from snode/pnode/tnode/fnode. See Table 4 below.	uint8_t[]	A list of integers between 0 and 255.	Depends on board type.
CH_field_type	Type of field to output. See Table 3 below.	uint8_t[]	A list of integers between 0 and 255.	Depends on board type.

Table 1: Model ID

Model ID	Model Name
0	RPICT8
1	RPICT7V1
2	RPICT4V3

Current/Voltage pairs

Current/Voltage pairs are small programs in the microcontroller that computes power given a current/voltage couple.

Four given parameters must be provided. They are the pin numbers where to find the current and voltage and also which slave (or master) is to be used.

For example if

HWSCT = 7 
HWMCPSCT = 6 
HWVOL = 0 
HWMCPVOL = 10

will use current ct1 (7) on slave 1 (6) computed against voltage1 (0) on master board (10).

The tables below gives all pin assignment:

Table 2: current_pin voltage_pin

Pin number snode_pin/pnode_pinI/pnode_pinV etc...	RPICT7V1	RPICT8	RPICT4V3
0	V1	CT8	V3
1	CT7	CT7	V2
2	CT6	CT6	V1
3	CT5	CT5	nc
4	CT4	CT4	CT4
5	CT3	CT3	CT3
6	CT2	CT2	CT2
7	CT1	CT1	CT1

Table 3: slave master pins

Pin number HWMCPSCT/HWMCPVOL	Board type
10	Master
6	Slave 1
7	Slave 2
8	Slave 3
9	Slave 4

Channels

We are referring as a channel here a data stream to be sent out. For example Vrms and Realpower derived from a same sensor will be two different channels.

These are configured with three parameters. The first one CHID is the node index of the list defined above. Note the first id is zero (0).
The second one CH_node_type is the type of node used. Either snode/pnode/tnode or fnode.
The thirsd one CH_field_type identifies the type of channel. See table 3 below.
For example:

CHID = 0
CH_node_type = 3
CH_field_type = 3

Uses voltage/current CV pair id 0. Node type is 3 which is a Power Node. Channel type is 3 which is Vrms. Basically this means output the Vrms value of the first Pnode.

The table below shows the convention being used:

Table 4: Field Definition

code	Channel Type	Description
0	None
1	Real Power (Active Power)	Real Power in Watts
2	Apparent Power	Apparent Power in VA. This is Irms*Vrms
3	Vrms	Rms Voltage in Volts.
4	Irms	Rms current in Ampere.
5	Estimated Power	Estimated Power in Watts. This is Irms*Vest.
6	Power Factor	Power Factor (no units). This is RealPower/ApparentPower.
7	Temperature	Temperature (Celsius). Only for RPIZCT4V3T1 & RPIZ_CT4V3T2.
8	Frequency	Frequency in Hertz. Only with version 3.0.2.
9	RTD Temperature	Temperature (Celsius). Only for RPIZ_CT4V3T2.
10	Reactive Power	Reactive power in VAR.
11	3Phase Real Power (Active Power).	3Phase Real Power in Watts.
12	3Phase Apparent Power.	3Phase Apparent Power in VA.
13	3Phase Reactive Power.	3Phase Apparent Power in VAR.
14	3Phase Power Factor.	3Phase Power Factor.
15	3Phase Vrms.	3Phase Rms Voltage in Volts.
16	3Phase Irms.	3Phase Rms current in Ampere.

Table 5: Node Types

code	Node Type	Description
2	snode	Signal Node. Compute RMS only of a single channel. Efficient and lightweight computation.
3	pnode	Power Node. Computes all power related values of a current/voltage pair. Requires definition of both current and voltage sensor ports.
4	fnode	Frequency Node. Computes frequency only on a given sensor port.
5	tnode	Three Phase Node. Same as pnode but for three phase.
7		Temperature.

Restore Default Config

If things go wrong it is possible to reinstate factory configuration.

4 letter code
The ideal scenario is when you have the 4 letter code provided with the card. If the code is XXXX you can restore factory config with

$ wget lechacal.com/hardware/c/XXXX.conf
$ lcl-rpict-config.py -a -w XXXX.conf

debug

Enabling debug can be done in the configuration by setting debug = 1.

debug = 1

At time of writing debug has no effect on the output. Timing information that was shown in version 3 of the same sketch will now be ported to the web tool.

How to reset the board

1. Auto reset

The board can be reset automatically with newest versions of the RPICT using the -a option.

lcl-rpict-config.py -a

or

lcl-rpict-config.py -a -w myfile.conf

Auto-reset is only available on some units. Version 3 hardware do not support auto-reset and manual reset must be used.

2. White Reset Button

If the board has a white button then press this button to reset the board.

Note that the button can be stiff when the board is brand new. If it fails to operate press the button 50 times or until it succeed with a strong push. Following that the button will be much easier to activate.

3. No Reset Button

Some of the older RPICT do not have the white button. These are the RPICT8 RPICT3V1 RPICT4T4 and RPICT4V3 version 1.

Use a small jumper to link the reset pin with the ground. This can be found on the 6x2 pins ISP connector. This is the stacking connector at the top. The two most left pins are the one to connect together (see picture).

Make contact with the two pins then remove the jumper. This will reset the board. Do not keep the pins connected. The contact must really brief and unique (avoid double contact).

4. Alternative reset method

Probably not the best recommended method but meanwhile really efficient.

Another way to reset the board is to keep the lcl-rpict-config.py command running and remove the board from the Raspberrypi. Then re-insert the board on the Raspberryi. This will guarantee the restart of the board.

Version History

Version 4.1.0

• Now using RPICTlib 1.5.0

Version 4.0.2

• Added temperature support for RPICT4W3T1/RPIZ_CT4V3T2. Must be enabled with the #define.

Version 4.0.1

• Blank configuration detection now done with version ID instead of magic number.
• Now using rpictlib v 1.4.1 for model definition in config. Beware this makes v4.0.0 incompatible with new configuration files.

Version 4.0.0

• Initial Release.
• Complete review.
• Now supports mixed computation nodes.
• i.e. 3 phase node can be setup along with single phase and current only nodes.
• Using B5 configuration type.
• Running RPICTlib 1.4.0.
• binary output has been removed.
• Now using dynamic arrays.
• Introduced current only node with faster sampling.
• Introduced 3 phase nodes.
• Offset filter set for quick response on the first 10 seconds of run (high cut off).
• Offset filter set for slower response past the 10 seconds of run (low cut off).