Latest revision as of 12:27, 23 February 2022

Overview

This page covers version 3.0.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

Output format (csv or Emonhub)
Nodeid (for Emonhub format)
Polling (polling interval of data)
Ical (current calibration value)
Vcal (Voltage calibration value)
Phasecal
Vest (estimated voltage for power estimate)
List of CV pairs to compute.
List of channels to output.

Limitations

Maximum Channels

Sketch 3.0 allows up to 28 Current/Voltage pair to be computed and 64 output channels. CV pairs compute Irms, Vrms, RealPower etc.
Max Nodes: 28
Max Channels: 64

To compute up to 40 CV pairs use the noOSC sketch. noOSC Sketch v1.1
The sketcch will have to be edited to your needs and uploaded to the arduino microcontroller.

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).

Preliminaries

python serial should be installed for the utility to run.

sudo apt-get install python-serial

RPICT Configuration tool

The configuration tool can be downloaded directly from the raspberrypi:

wget lechacal.com/RPICT/tools/lcl-rpict-config.py.zip
unzip lcl-rpict-config.py.zip
sudo cp lcl-rpict-config.py /usr/local/bin

Reading current configuration

Using the configurator without option only read 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 has received the reset the configuration will be shown.How to reset the board.

# 
# Configuration in memory:
# 
# Structure: 0xb4
# Format: 3
# NodeId: 11
# Polling: 3000
# KCAL:   1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0 1.0  560.0  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311
# PHASECAL: 0
# VEST: 240.000000
# xpFREQ: 50
# Ncycle: 20
# Nnode: 7
# Nchan: 15
# debug: 1
# Complete configuration in /tmp/rpict.conf
#

Every time the configuration is read from the board it stores a copy in the /tmp/rpict.config 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 RPICT7V1. Such file contains this below.

[main]
format = 3
nodeid = 11
polling = 3000
kcal = 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 560.0 83.33 83.33 83.33 83.33 83.33 83.33 83.33
phasecal = 0
vest = 240.0
xpFREQ = 50
Ncycle = 20
Nnode = 7
Nchan = 15
HWSCT = 7 6 5 4 3 2 1 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255
HWMCPSCT = 10 10 10 10 10 10 10 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255
HWVOL = 0 0 0 0 0 0 0 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255
HWMCPVOL = 10 10 10 10 10 10 10 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255
CHTYPE = 1 1 1 1 1 1 1 4 4 4 4 4 4 4 3 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255
CHID = 0 1 2 3 4 5 6 0 1 2 3 4 5 6 0 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255 255
debug = 1

All these parameters are explained in details further below this page.

To build this file this is an online configurator.

Online configurator.

One can modify the file manually and save it in a file called my_rpict7v1.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_rpict7v1.conf

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

# RPICT Configuration Utility
# Configuration will be overwritten (Ctrl C to cancel)
# Now reset RPICT hardware
# 
# Configuration in memory:
# 
# Structure: 0xb4
# Format: 3
# NodeId: 11
# Polling: 3000
# KCAL:   1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0   1.0  560.0  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311
# PHASECAL: 0
# VEST: 240.000000
# xpFREQ: 50
# Ncycle: 20
# Nnode: 7
# Nchan: 15
# debug: 1
# Complete configuration in /tmp/rpict.conf
# 
# Writing configuration with file B4/rpict7v1.conf
# 
# Configuration in memory:
# 
# Structure: 0xb4
# Format: 3
# NodeId: 11
# Polling: 10000
# KCAL:   1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0   1.0  560.0  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311  83.3300018311
# PHASECAL: 0
# VEST: 240.000000
# xpFREQ: 50
# Ncycle: 20
# Nnode: 7
# Nchan: 15
# debug: 1
# Complete configuration in /tmp/rpict.conf
#

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	0 - CSV 1 - deprecated 2 - deprecated 3 - Emonhub 4 - Binary	3
nodeid	Device identification number. Well used with emonhub format.	uint8_t	Any number between 0 and 255.	11
polling	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 slave1. The second 8 values are for slave2 etc. The last 8 values are for the master board. Each values inside a block of 8 must be in the same order as in Table 1 below. The example above shows for a rpict7v1 vcal=560 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 220V or 110V. 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. Former sketches were computing real power only if this parameter was set to 0. This is no longer the case here.	float	Any floating point number.	240.0
xpFREQ	Expected Frequency. The expected frequency to be measured 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 of 10 or 20 are usually good.	uint8_t	An integer between 1 and 255	20
Nnode	Number of Current/Voltage pair to compute.	uint8_t[28]	An integer between 0 and 255	Depends on board type.
Nchan	Number of channels (or fields) to output.	uint8_t	An integer between 0 and 255	Depends on board type.
HWSCT	Pin configuration of a current input. Only first Nnode are relevant.	uint8_t[28]	An integer between 0 and 255	Depends on board type.
HWMCPSCT	Master or slave identifier for current input. Only first Nnode are relevant.	uint8_t[28]	An integer between 0 and 255	Depends on board type.
HWVOL	Pin configuration of a voltage input. Only first Nnode are relevant.	uint8_t[28]	An integer between 0 and 255	Depends on board type.
HWMCPVOL	Master or slave identifier for voltage input. Only first Nnode are relevant.	uint8_t[28]	An integer between 0 and 255	Depends on board type.
CHTYPE	Type of channel to output. See table below.	uint8_t[64]	An integer between 0 and 255	Depends on board type.
CHID	Identifies from which combination node within HWSCT the channel should be output. 0 being the first node.	uint8_t[64]	An integer between 0 and 255	Depends on board type.
debug	Turn debug on/off	uint8_t	0 - OFF 1 - ON	0

The 255 in the configuration file are just place holders.

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 1: current_pin voltage_pin
Pin number HWSCT/HWVOL	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
127	Vest	Vest	Vest

- Vest is estimated Voltage. If the pin is set to 127 the CV pair will compute only against Vest and not measured Voltage.

Table 2: 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 refering 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 two numbers. The first one is the CV pair id defined above. Note the first combination id is zero (0). The second number identifies the type of channel. For example:

CHTYPE = 3 
CHID = 0

Uses voltage/current CV pair id 0. Channel type 3 which is Vrms (as the table below describes).

The table below shows the convention being used:


code	Channel Type	Description
0	None
1	Real 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.

Restore Default Config

If things go wrong it is possible to reinstate default configuration as shown below.

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

RPICT7V1

$ wget lechacal.com/RPICT/config/B4/rpict7v1.conf
$ lcl-rpict-config.py -a -w rpict7v1.conf

RPICT8

$ wget lechacal.com/RPICT/config/B4/rpict8.conf
$ lcl-rpict-config.py -a -w rpict8.conf

RPICT4V3

$ wget lechacal.com/RPICT/config/B4/rpict4v3.conf
$ lcl-rpict-config.py -a -w rpict4v3.conf

Some stacked configuration

RPICT7V1 + RPICT8

A very common setup stacking one RPICT7V1 as master with one RPICT8 as slave. Offering one voltage to compute against 15 CT. Config given for the 100A rating. Output is

Voltage RMS
Real Power 1 to 7 master
Real Power 1 to 8 slave

$ wget lechacal.com/RPICT/config/B4/stack_ct7v1_ct8.conf
$ lcl-rpict-config.py -w stack_ct7v1_ct8.conf

debug

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

debug = 1

When reading the data stream some extra information will be shown. One should set debug = 0 back to return to normal usage.

An example of the debug information will look like this below.

pi@raspberrypi:~ $ cat /dev/ttyAMA0
11 244.2 242.1 243.2 6.6 47.1 22.5 20.8
# Offsets I: 2041.00 2017.60 2045.70 2045.46 
# Offsets V: 2012.01 2019.80 2024.21 2022.31 
# Scan interval (ms): 1616
11 243.5 241.6 242.4 4.6 22.0 11.7 19.6
# Offsets I: 2039.77 2012.66 2042.19 2043.30 
# Offsets V: 2002.89 2010.56 1997.96 2004.81 
# Scan interval (ms): 1616
11 243.8 241.4 241.8 3.4 -4.4 2.8 -1.4

Find Minimum polling interval

In the above example the scan interval is reported at 1616 milliseconds. This means that all acquisitions and computations take approximatively 1.6 seconds to complete. One might set the polling interval safely to 2 seconds in this case (polling = 2000).

Offsets

The offset of each channel is also reported. This is the zero level on the ADC scale. We expect values to be around 2048 but do not need to be specifically accurate.

Number of samples

Debug can also indicate how many samples will be used to acquire the waveform. For this read the data with the cat command and press the reset button. Debug will show the following line:

# Number of samples: 784

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's 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 3.2.0

Now uses RPICTlib 1.2.0
Sampling interval boosted up to 4.4kHz instead of 3.3kHz
Irms with 3 decimals

Version 3.1.0

Irms now in A instead of mA
Added reactive power

Version 3.0.2

Uses RPICTlib 1.1.0
Frequency Support
Temperature support for RPI_T8

Version 3.0.1

Uses RPICTlib 1.0.1
Sampling up to 3.3kHz

Version 3.0.0

Now using RPICTlib library
Higher accuracy using much more efficient computation of RMS signal.
Introduced better sampling of data using a sampling interval of 2kHz.
User has control of window length of sampling by editing the number of cycles to acquire. Few cycles => faster acquisition, instantaneous reading. Many cycles => slower acquisition, smoother readings.
For the window length of sampling user can now set which frequency is expected (typically 50 or 60Hz).
Debug option. User can view more information behind the scene setting debug=1.
Phasecal is now set using signed numbers (e.g. -1 0 +1). Also phasecal is now more intuitive to adjust.
Output data with 'nan' if an error happen.
Trigger an error (nan) if data is out of range. (i.e > ADC max).
Trigger an error (nan) if the MCU can not cope with sampling speed. (We expect this to never happen unless you modify the sampling interval yourself).
Debug mode reports the fastest polling that can be set for a given configuration.
Debug mode reports the zero offset. (advanced usage).
Power factor outputs 3 digits after decimal.
Pin number for current or voltage are now in range 0 to 7. (no longer 1 to 8).
Using B4 structure for configuration.
Also countless code optimisation found here and there.
Some effort to make the code clearer. WIP.

Over Serial Configuration - Sketch 3.0: Difference between revisions