Difference between revisions of "Energy Module Commands"

From OpenMotics
Jump to navigation Jump to search
 
(57 intermediate revisions by 3 users not shown)
Line 24: Line 24:
 
== FIV : FirmwareIDVersion ==
 
== FIV : FirmwareIDVersion ==
  
−
Gives back the firmware ID and version.
+
Gives back the firmware ID and version. Depending if the module is in application or in bootloader mode, an other value is returned.
  
 
* Input
 
* Input
 
** none
 
** none
 
* Output
 
* Output
−
** ID and version: 16 chars (ex. "OMFPC_0_1_1")
+
** ID and version: 16 chars (ex. "OMFPC_3_2_1" or "OMFBC_1_2_3")
  
 
=Power=
 
=Power=
Line 95: Line 95:
 
** none
 
** none
 
* Output
 
* Output
−
** Energy : 12xUINT32 [kWh]
+
** Energy : 12xINT32 [kWh]
  
 
or set the energy to a specific value
 
or set the energy to a specific value
Line 101: Line 101:
 
* Input
 
* Input
 
** Fixed value : 1 BYTE set to 0xAA
 
** Fixed value : 1 BYTE set to 0xAA
−
** EnergySetValue : 12xUINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
+
** EnergySetValue : 12xINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
 
* Output
 
* Output
 
** none
 
** none
Line 112: Line 112:
 
** none
 
** none
 
* Output
 
* Output
−
** EnergyDay : 12xUINT32 [kWh]
+
** EnergyDay : 12xINT32 [kWh]
  
 
or set the energy to a specific value
 
or set the energy to a specific value
Line 118: Line 118:
 
* Input
 
* Input
 
** Fixed value : 1 BYTE set to 0xAA
 
** Fixed value : 1 BYTE set to 0xAA
−
** EnergySetValue : 12xUINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
+
** EnergySetValue : 12xINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
 
* Output
 
* Output
 
** none
 
** none
Line 129: Line 129:
 
** none
 
** none
 
* Output
 
* Output
−
** EnergyNight : 12xUINT32 [kWh]
+
** EnergyNight : 12xINT32 [kWh]
  
 
or set the energy to a specific value
 
or set the energy to a specific value
Line 135: Line 135:
 
* Input
 
* Input
 
** Fixed value : 1 BYTE set to 0xAA
 
** Fixed value : 1 BYTE set to 0xAA
−
** EnergySetValue : 12xUINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
+
** EnergySetValue : 12xINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
 +
* Output
 +
** none
 +
 
 +
== VST : VoltageSampleTime ==
 +
 
 +
Gives back 1 period of a voltage channel. The phase is locked to a positive zerocross of the voltage. The data is given back in 2 parts because the data is to big for 1 call.
 +
 
 +
* Input
 +
** channel : 1 BYTE [0-11] : [0-3] = voltage A; [4-8] = voltage B; [9-11] = voltage C
 +
** part : 1xBYTE [0-1] select if you want the first or last 50 samples of the voltage
 +
* Output
 +
** voltageSamples : 50xFLOAT [V] gives back NaN values if 1 period is done.
 +
 
 +
== VSF : VoltageSampleFreq ==
 +
 
 +
Gives back the frequencycomponents of a voltage channel.
 +
 
 +
* Input
 +
** channel : 1 BYTE [0-11] : [0-3] = voltage A; [4-8] = voltage B; [9-11] = voltage C
 +
** numof : 1xBYTE [0-20] select the number of frequency components you want to get from that voltage channel
 +
* Output
 +
** voltageComponents : [numof]xFLOAT [V] : first is DC, second sample is first harmonic
 +
** PhaseComponents : [numof]xFLOAT [rad]
 +
 
 +
== CST : CurrentSampleTime ==
 +
 
 +
Gives back 1 period of a current channel. The phase is locked on the corresponding voltage for that channel. The data is given back in 2 parts because the data is to big for 1 call.
 +
 
 +
* Input
 +
** channel : 1 BYTE [0-11] current channel
 +
** part : 1xBYTE [0-1] select if you want the first or last 50 samples of the current
 +
* Output
 +
** currentSamples : 50xFLOAT [A] gives back NaN values if 1 period is done.
 +
 
 +
== CSF : CurrentSampleFreq ==
 +
 
 +
Gives back the frequency components of a current channel.
 +
 
 +
* Input
 +
** channel : 1 BYTE [0-11]
 +
** numof : 1xBYTE [0-20] select the number of frequency components you want to get from that current channel
 +
* Output
 +
** CurrentComponents : [numof]xFLOAT [A] : first is DC, second sample is first harmonic
 +
** PhaseComponents : [numof]xFLOAT [rad]
 +
 
 +
= PowerSettings =
 +
 
 +
== ENM : EnergyMode==
 +
 
 +
* The energy level is calculated from the power in time.
 +
* Depending on the energy mode, when power is negative, the energy level can decrease, hold or increase its value, depending on the amount of power.
 +
* modes:
 +
** 0 = Hold the energy level fixed when there is negative power on the channel.
 +
** 1 = Increase the energy level (use the abs value)
 +
** 2 = Decrease the energy level
 +
 
 +
Gives back the energy mode
 +
 
 +
* Input
 +
** none
 +
* Output
 +
** EnergyMode : 12xBYTE
 +
 
 +
or set the energy mode
 +
 
 +
* Input
 +
** EnergyMode : 12xBYTE
 +
* Output
 +
** none
 +
 
 +
== EPT : EnergyPowerThreshold==
 +
 
 +
Energy is increased depending on the amount of power. To avoid very small power levels to increase the energy level, a threshold can be set as a minimum amount of power needed to increase the energy level.
 +
 
 +
Gives back the power threshold.
 +
 
 +
* Input
 +
** none
 +
* Output
 +
** PowerThreshold: 1xfloat [W]
 +
 
 +
or set the power threshold.
 +
 
 +
* Input
 +
** PowerThreshold: 1xfloat [W]
 
* Output
 
* Output
 
** none
 
** none
Line 148: Line 233:
 
** none
 
** none
  
−
== OSC : Oscilloscope ==
+
== SCI : SetCurrentInverse==
 +
 
 +
Per channel you can specify if the current signal should be interpreted inverse or not. This is important to have the right sign of the power calculated per channel.
 +
 
 +
Set the current inverse mode.
 +
 
 +
* Input
 +
** CurrentInverse: 12xBYTE [not inverse:0,inverse:1]
 +
* Output
 +
** none
 +
 
 +
== CCF: CurrentClampFactor==
 +
 
 +
* Per channel a different current clamp can be connected.
 +
* The calibration values are done for a 50A clamp.
 +
* If you connect a different type of current clamp a compensation can be set via the CurrentClampFactor.
 +
** ex. for a 25A current clamp a factor of 0.5 can be set.
 +
 
 +
Set the CurrentClampFactor.
 +
 
 +
* Input
 +
** ClampFactor: 12xFLOAT
 +
* Output
 +
** none
  
 
=Calibration=
 
=Calibration=
Line 154: Line 262:
 
== SVO : SetVoltage ==
 
== SVO : SetVoltage ==
  
−
parameter = 1x4 bytes type float in [V]
+
* There are 3 voltage channels that can be calibrated.
−
There are 3 voltage channels that can be calibrated.
+
* The parameter should be the voltage connected to one or more of the voltage channels.
−
The parameter should be the voltage connected to one or more of the voltage channels.
+
* Only the channels that have a voltage above 10V (before calibration) will be calibrated. This way you can calibrate every channel separately or in one shot.
−
Only the channels that have a voltage above 10V (before calibration) will be calibrated. This way you can calibrate every channel separately or in one shot.
+
* If the calibrated value deviate more than factor 2 (in both directions), the value will also be 'floored'.
−
If the calibrated value deviate more than factor 2 (in both directions), the value will also be 'floored'.
+
* [edit] Calibration of the voltage
−
[edit] Calibration of the voltage
+
 
 +
* Input
 +
** Voltage : 1xFLOAT [V]
 +
* Output
 +
** none
 +
 
 +
== SDV : SetDefaultVoltage ==
 +
 
 +
Sets all the calibration values for the voltage channels to the default value
 +
 
 +
* Input
 +
** none
 +
* Output
 +
** none
  
 
== SCU : SetCurrent ==
 
== SCU : SetCurrent ==
  
−
parameter = 1x4 bytes type float in [A]
+
* There are 12 current channels that can be calibrated.
−
There are 12 current channels that can be calibrated.
+
* The parameter should be the current connected to one or more of the current channels. <<-- what with different current-sensors? should be calibrated with 1 current sensor and an extra parameter should be used to have an extra * factor to use in the calculation.
−
The parameter should be the current connected to one or more of the current channels. <<-- what with different current-sensors? should be calibrated with 1 current sensor and an extra parameter should be used to have an extra factor to use in the calculation.
+
* Only the channels that have a current above 0.1A (before calibration) will be calibrated. This way you can calibrate every channel separately or in one shot.
−
Only the channels that have a current above 0.1A (before calibration) will be calibrated. This way you can calibrate every channel separately or in one shot.
+
* If the calibrated value deviate more than factor 2 (in both directions), the value will also be 'floored'.
−
If the calibrated value deviate more than factor 2 (in both directions), the value will also be 'floored'.
+
 
 +
* Input
 +
** Current : 1xFLOAT [A]
 +
* Output
 +
** none
 +
 
 +
== SDC : SetDefaultCurrent ==
 +
 
 +
Sets all the calibration values for the current channels to the default value
 +
 
 +
* Input
 +
** none
 +
* Output
 +
** none
  
−
== SOS : SetOffset ==
+
== COF : CalibrationOffset ==
  
 
=Addressing=
 
=Addressing=
Line 175: Line 309:
 
== AGT : AddressmodeGoTo ==
 
== AGT : AddressmodeGoTo ==
  
−
== WAA : WantAnAddress ==
+
== WAD : WantAnAddress ==
 +
 
 +
Sends the firmware ID and version (like in the FIV command). This is the only command that asynchronously can be send from a module when in address mode.
 +
 
 +
* Output
 +
** ID and version: 16 chars (ex. "OMFPC_3_2_1")
  
 
== SAD : SetAddress ==
 
== SAD : SetAddress ==
Line 183: Line 322:
 
== BGT : BootloaderGoTo ==
 
== BGT : BootloaderGoTo ==
  
−
Go to bootloader
+
Go to bootloader, to check if the module is in bootloader mode, you can ask FIV : FirmwareIDVersion and see if OMFBC... is given back in stead of OMFPC...
  
 
* Input
 
* Input
Line 197: Line 336:
 
** none
 
** none
  
−
value between 10 and ... (first 10 pages are bootloader)
+
value between 6 and 63 (first 6 pages are bootloader)
  
 
one page is 4096 bytes so if you delete 1 page you have to do some BWC's to fill it up
 
one page is 4096 bytes so if you delete 1 page you have to do some BWC's to fill it up
Line 223: Line 362:
  
 
== EEP : EEPROMdata ==
 
== EEP : EEPROMdata ==
 +
 +
Gives back some EEPROM bytes from a certain address
 +
 +
* Input
 +
** Address : 1xUINT16
 +
** Length : 1xUINT16
 +
* Output
 +
** Data : <Length>xBYTE data starting from position <Address>
 +
 +
or set some bytes to the EEPROM
 +
 +
* Input
 +
** Address : 1xUINT16
 +
** DataBytes : 1..NxBYTE
 +
* Output
 +
** none
 +
 +
== EEC : EEPROMcleardata==
 +
 +
Clear some pages in the EEPROM
 +
 +
* Input
 +
** Page : 1..NxBYTE : always starting from page 0 to page N-1. Only the pages where the corresponding byte is set to 0x01 will be cleared.
 +
* Output
 +
** none
 +
 +
PageInfo:
 +
* Page 0 = General data
 +
* Page 1 = Calibration data
 +
* page 2-3 = kWh data
 +
 +
== RIC : RAWICCommand [Don't use] ==
 +
 +
Info on how and what to send , see: manual of IC [http://www.cirrus.com/en/pubs/proDatasheet/CS5480_F3.pdf CS5480]
 +
 +
send something to a specific IC some data (set).
 +
 +
* Input
 +
** ChipNumber: 1xBYTE
 +
** Bank : 1xBYTE
 +
** Data : 4xBYTE
 +
* Output
 +
** none
 +
 +
If you send a read command, the data can be retrieved via this get. If the data is not yet ready a NAK is send
 +
 +
* Input
 +
** none
 +
* Output
 +
** Data : 4xBYTE
 +
 +
== STA : GetStates ==
 +
 +
Get all states of the statemachines internally.
 +
 +
*Only the first x bytes are used:
 +
**[0]=I2C_1.State I2C_STATE
 +
**[1]=I2C_3.State I2C_STATE
 +
**[2]=spiState SPI_STATE
 +
**[3]=buttonmode BUTTON_STATE
 +
**[4]=DFTState DFT_STATE
 +
**[5]=CalibState CALIB_STATE
 +
**[6]=OscPostProcessState OSC_POSTPROCESS_STATE
 +
**[7]=SPISendOscState SPI_SEND_OSC_STATE
 +
**[8]=OscState OSC_STATE
 +
**[9]=EnergyState ENERGY_STATE
 +
**[10]=SpiRmsState SPI_RMS
 +
**[11]=FRAMState FRAM_STATE
 +
**[12]=CommunicationStatus COMMUNICATION_STATUS
 +
**[13]=CommState TSTATES
 +
**[14]-[31]= Not used yet
 +
 +
* Input
 +
** none
 +
* Output
 +
** Data : 32xBYTE
 +
 +
== NOS : NumOfStartups ==
 +
 +
Get the number of cold or hot resets of the device
 +
 +
* Input
 +
** none
 +
* Output
 +
** Data : 1xUINT32
 +
 +
== ELN : ErrorListNumOf ==
 +
 +
Get the number of errors in the error list
 +
 +
* Input
 +
** none
 +
* Output
 +
** Data : 1xUINT16
 +
 +
or clear the errorlist by sending a Set command.
 +
 +
* Input
 +
** none
 +
* Output
 +
** none
 +
 +
== ELA : ErrorListAt ==
 +
 +
Get error from the errorlist at place: address (0 = oldest, ErrorListNumOf or size of list = newest error in errorlist)
 +
 +
* Input
 +
** address :
 +
* Output
 +
** errorcode : 1xBYTE type of error , see errorcodelist
 +
** errorlevel : 1xBYTE 0=highest
 +
** numOfOoccur : 1xUINT16 of errorcode type
 +
** timestamp : 1xUINT32 occurance of this error based on TON : TimeOn time
 +
** text : 24xCHAR error explained in string format (can contain values in string format)
 +
 +
*errorcodelist:
 +
**ERROR_CODE_NO_FRAM_DETECTED=10
 +
**ERROR_CODE_NO_TOPPANEL_DETECTED=11
 +
**ERROR_CODE_NO_POWERIC_DETECTED=12
 +
**ERROR_CODE_ERROR_IN_FRAM=100
 +
**ERROR_CODE_ERROR_IN_TOPPANEL=101
  
 
=Error codes=
 
=Error codes=
Line 234: Line 494:
 
*REPLY_NAK_NO_GET = 6
 
*REPLY_NAK_NO_GET = 6
 
*REPLY_NO_REPLY = 7
 
*REPLY_NO_REPLY = 7
 +
 +
 +
 +
 +
 +
 +
 +
 +
=Command summary=
 +
 +
{| class="wikitable"
 +
| Type || Name || mode || Request count || request type || request unit || request description || response count || response type || response unit || response description || Comment
 +
|-
 +
| GST || FUNC_GeneralStatus || G || - || - || - || - || 1 || UINT8 || - || value 0xA5 || dummy implementation
 +
|-
 +
| TON || FUNC_TimeOn || G || - || - || - || - || 1 || UINT32 || s || Time since on in seconds ||
 +
|-
 +
| NOS || FUNC_NumOfStartups || G || - || - || - || - || 1 || UINT32 || - || Startup count ||
 +
|-
 +
| FST || FUNC_FeedStatus || G || - || - || - || - || 12 || UINT32 || - || IC status for 12 channels ||
 +
|-
 +
| FCO || FUNC_FeedCounter || G || - || - || - || - || 1 || UINT16 || - || Number of channels ||
 +
|-
 +
| VOL || FUNC_Voltage || G || - || - || - || - || 12 || FLOAT || V || Actual RMS voltage ||
 +
|-
 +
| FRE || FUNC_Frequency || G || - || - || - || - || 12 || FLOAT || Hz || Actual frequency ||
 +
|-
 +
| CUR || FUNC_Current || G || - || - || - || - || 12 || FLOAT || A || Actual RMS current ||
 +
|-
 +
| POW || FUNC_Power || G || - || - || - || - || 12 || FLOAT || W || Actual power ||
 +
|-
 +
| RPO || FUNC_ReactivePower || G || - || - || - || - || 12 || FLOAT || W || Reactive power ||
 +
|-
 +
| ENE || FUNC_Energy || S || 1 +  12 || UINT8 FLOAT || - kWh || 0xAA EnergyTgt Total || - || - || - || - || 0xAA start byte is qualifier for 12 floats following
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || FLOAT || kWh || EnergyActual Total ||
 +
|-
 +
| EDA || FUNC_EnergyDay || S || 1 +  12 || UINT8 FLOAT || - kWh || 0xAA EnergyTgt Day || - || - || - || - || 0xAA start byte is qualifier for 12 floats following
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || FLOAT || kWh || EnergyActual Day ||
 +
|-
 +
| ENI || FUNC_EnergyNight || S || 1 +  12 || UINT8 FLOAT || - kWh || 0xAA EnergyTgt Night || - || - || - || - || 0xAA start byte is qualifier for 12 floats following
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || FLOAT || kWh || EnergyActual Night ||
 +
|-
 +
| ENM || FUNC_EnergyMode || S || 12 || UINT8 || enum || mode || - || - || - || - || 0 : ENERGY_DONT_ADD_WHEN_POWER_NEG 1 : ENERGY_ADD_WHEN_POWER_NEG 2 : ENERGY_SUBTRACT_WHEN_POWER_NEG
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || UINT8 || enum || mode ||
 +
|-
 +
| EPT || FUNC_EnergyPowerThreshold || S || 1 || FLOAT || W || target value || - || - || - || - || Power values below this are ignored default is 0.1W
 +
|-
 +
|  ||  || G || - || - || - || - || 1 || FLOAT || W || present value ||
 +
|-
 +
| EPT ||  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||
 +
|-
 +
| FIV || FUNC_FirmwareIDVersion || G || - || - || - || - || 12 || string || ascii || Returns Program ID ||
 +
|-
 +
|  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||
 +
|-
 +
| SDN || FUNC_SetDayNight || S || 1 || UINT8 || bool || current state || - || - || - || - || 0 : Night  1 : Day
 +
|-
 +
| SCI || FUNC_SetCurrentInverse || S || 12 || UINT8 || bool || target value ||  ||  ||  ||  || determines whether sensor values are inverted or not 0 : Normal  1: Invert
 +
|-
 +
|  ||  || G ||  ||  ||  ||  || 12 || UINT8 || bool || present value ||
 +
|-
 +
| CCF || FUNC_CurrentClampFactor || S || 12 || FLOAT || - || target value || - || - || - || - || determines sensitivity of current sensors 1.0 for 50A current sensor 0.5 for 25A current sensor
 +
|-
 +
|  ||  || G || 0 || - || - || - || 12 || FLOAT || - || present value ||
 +
|-
 +
| SVO || FUNC_SetVoltage || S || 1 || FLOAT || V || reference value || 0 || - || - || - || All voltages are recalibrated to this level
 +
|-
 +
|  ||  || S || 1 +  1 || BYTE FLOAT || - V || channel reference value || 0 || - || - || - || All channels using the same VT are recalibrated to this level (0..3, 4..7, 8..11)
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || FLOAT || - || present value || Returns raw calibration values. Default is 3.05e-5 which typically results in 290V
 +
|-
 +
| SCU || FUNC_SetCurrent || S || 1 || FLOAT || A || reference value || - || - || - || - || ALL CURRENTS are recalibrated to this level. Make sure they all carry the reference current !
 +
|-
 +
|  ||  || S || 1 +  1 || BYTE FLOAT || - A || channel reference value || 0 || - || - || - || Only the specified channelis recalibrated to this level (valid 0..11)
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || FLOAT || - || present value || Returns raw calibration values. Default for 50A/330mV sensor is  2.34e-6
 +
|-
 +
| SDV || FUNC_SetDefaultVoltage || S || - || - || - || - || - || - || - || - || Sets the voltage calibrations to default which typically results in 290V
 +
|-
 +
| SDC || FUNC_SetDefaultCurrent || S || - || - || - || - || - || - || - || - || Sets the current calibrations to default
 +
|-
 +
| SOS || Func_SampleOffsets || S || - || - || - || - || - || - || - || - || Accepts present current and power readings as offset
 +
|-
 +
| SDO || Func_SetDefaultOffset || S || - || - || - || - || - || - || - || - || Clears the current and power offsets
 +
|-
 +
| SPC || FUNC_SetPhaseComp || S || 6 || UINT32 || - || calculated values || 0 || - || - || - || One value for each CS5480 on the board
 +
|-
 +
|  ||  || G || - || - || - || - || 6 || UINT32 || - || values saved in calibration data  || One value for each CS5480 on the board
 +
|-
 +
| SCO || FUNC_SetCurrentOffsets || S || 12 || FLOAT || A || current offset || - || - || - || - ||
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || FLOAT || A || current offset ||
 +
|-
 +
| SPO || FUNC_SetPowerOffsets || S || 12 || FLOAT || W || power offset || - || - || - || - ||
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || FLOAT || W || power offset ||
 +
|-
 +
| COF || FUNC_CalibrationOffset || S || - || - || - || - || - || - || - || - || Triggers current offset calibration Make sure no current flows through any sensor
 +
|-
 +
|  ||  || G || - || - || - || - || 12 || FLOAT || ? || calibrated value || Returns calibratedoffset values These ARE NOT USED by the application
 +
|-
 +
| VST || FUNC_VoltageSampleTime || G || 1 1 || UINT8 UINT8 || - - || channel part || 50 || FLOAT || V || series of voltage measurements || Returns for the specified channel (0-11)  a part (0-1) of the real-time VOLTAGE waveform.
 +
|-
 +
| VSF || FUNC_VoltageSampleFreq || G || 1 1 || UINT8 UINT8 || - - || channel number || number || FLOAT || Hz? || series of frequencies from Fourier Transform || Returns for the specified channel (0-11) the specified number of frequencies resulting from an FFT on the VOLTAGE waveform
 +
|-
 +
| CST || FUNC_CurrentSampleTime || G || 1 1 || UINT8 UINT8 || - - || channel part || 50 || FLOAT || V || series of current measurements || Returns for the specified channel (0-11)  a part (0-1) of the real-time CURRENT waveform.
 +
|-
 +
| CSF || FUNC_CurrentSampleFreq || G || 1 1 || UINT8 UINT8 || - - || channel number || number || FLOAT || dB? || series of frequencies from Fourier Transform || Returns for the specified channel (0-11) the specified number of frequencies resulting from an FFT on the CURRENT waveform
 +
|-
 +
|  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||
 +
|-
 +
| BGT || FUNC_BootloaderGoTo || S/G || - || - || - || - || - || - || - || - || Performs a system reset, resulting in a jump to boot
 +
|-
 +
| RES || FUNC_Hotresetthedevice || S/G || - || - || - || - || - || - || - || - || Performs a system reset, resulting in a jump to boot
 +
|-
 +
| AGT || FUNC_AddressmodeGoTo || S || 1 || UINT8 || bool || mode || - || - || - || - || 0 : normal mode  1: address mode
 +
|-
 +
| WAD || FUNC_WantAnAddress || N/A || - || - || - || - || - || - || - || - || Module will send "WAD" when it's put in addressmode. It shall never receive this command
 +
|-
 +
| GAD || FUNC_GetAddress || G || - || - || - || - || 1 || UINT8 || bin || module address || also responds to ADDRESS 255 regardless the actual address
 +
|-
 +
| SAD || FUNC_SetAddress || S || 1 || UINT8 || - || module address || - || - || - || - || Sent in response to a "WAD" request. Only accepted while module is in addressmode
 +
|-
 +
|  ||  || S || 1 +16 || UINT8 UINT8 || - || Module address Module Serial nr. ||  ||  ||  ||  || Sent to force change the address of the module. Only accepted in addressmode and with correct serial number.
 +
|-
 +
| SSN || FUNC_SetSerialNumber || S || 16 || UINT8 || char || serial number || - || - || - || - ||
 +
|-
 +
|  ||  || G || - || - || - || - || 16 || UINT8 || char || serial number  ||
 +
|-
 +
| SBO || FUNC_SetBoardOptions || S || 4 || UINT8 || bin || Board assembly info || - || - || - || - || Byte0: UseCorrectedCCF - 0 = No, 1 = Yes Byte1: Boardtype - 0x52 for OMHEY5.2 Byte2: Assembly option1-2 - unassigned atm Byte3: EOLdataVer (read only - ignored in write)
 +
|-
 +
|  ||  || G || - || - || - || - || 4 || UINT8 || bin || Board assembly info ||
 +
|-
 +
|  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||
 +
|-
 +
| WED || FUNC_WriteEolDataToFlash || S || 4 || UINT8 || bin || magic number 0xA55A7F80 || - || - || - || - || Writes 256bytes of  EOL data to flash page 0x1D00500
 +
|-
 +
|  ||  || G || - || - || - || - || 1 || UINT8 || bool || status || 0: EOL data not read from FLASH 1: EOL data read from FLASH
 +
|-
 +
| EEP || FUNC_EEPROMdata || S || 1 var || UINT16 UINT8 || - - || target address || - || - || - || - || A variable number of BYTEs is written  to EEPROM - mirror Address range 0x0000 - 0x07FF (2kB)
 +
|-
 +
|  ||  || G || 1 1 || UINT16 UINT16 || - - || source address number  || number || UINT8 || - || EEPROM data || A variable number of BYTEs is read from the EEPROM mirror  - Address range 0x0000 - 0x07FF (2kB)
 +
|-
 +
| EEC || FUNC_EEPROMcleardata || S || var || UINT8 || bool || list of pages || - || - || - || - || this function expects a list of up to 8 bool values. The index selects the page to be cleared. The first value always maps to page 0.  If the value == 1, the page is set to 0xFF e.g. 01110001 will clear pages 1,2,3 and 7
 +
|-
 +
|  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||  ||
 +
|-
 +
| RIC || FUNC_RAWICCommand || S || 1 1 1 || UINT8 UINT8 UINT32 || - - - || IC index (0..5) bank (0..1) Command || - || - || - || - || sends a raw command to one of the CS5480
 +
|-
 +
|  ||  || G || - || - || - || - || 1 || UINT32 || - || Readback of last command ||
 +
|-
 +
| ELA || FUNC_ErrorListAt || G  || 1 || UINT16 || - || errorNumber || 32 || UINT8 ||  || ErrorList[errorNumber] ||  ERROR_CODE errorcode  BYTE  errorlevel//zero is highest prior  UINT16  numOfOoccur  UINT32  timestamp  BYTE  text[24];
 +
|-
 +
| ELN || FUNC_ErrorListNumOf || S || - || - || - || - || - || - || - || - || Clears ErrorList
 +
|-
 +
|  ||  || G || - || - || - || - || 1 || UINT16 || - || Number of errors ||
 +
|-
 +
| ERL || FUNC_ErrorReportList || G || - || - || - || - || n || UINT8 || - || List of up to 16 Errors || List of errors which have occurred at least once since ELN S
 +
|-
 +
| STA || FUNC_GetStates || G || - || - || - || - || 32 ||  ||  || 14 bytes, but 32 are sent - will contain rubbish || states[0]=(BYTE)I2C_1.State;    states[1]=(BYTE)I2C_3.State;    states[2]=(BYTE)spiState;    states[3]=(BYTE)buttonmode;    states[4]=(BYTE)DFTState;    states[5]=(BYTE)CalibState;    states[6]=(BYTE)OscPostProcessState;  states[7]=(BYTE)SPISendOscState;  states[8]=(BYTE)OscState;    states[9]=(BYTE)EnergyState;    states[10]=(BYTE)SpiRmsState;    states[11]=(BYTE)FRAMState;    states[12]=(BYTE)CommunicationStatus;  states[13]=(BYTE)CommState;   
 +
|-
 +
| IND || FUNC_Indicate || S || 1 || UINT 8 || bool || Indicate state ||  ||  ||  ||  || Indicate the module by the LED’s
 +
|-
 +
| BRI || Bootloader Read chip ID || G || - || - || - || - || 8 || UINT8 ||  || Flash Size Device ID || Buffer[0] = BMXPFMSZ &amp; 0xFF;    Buffer[1] = (BMXPFMSZ &gt;&gt; 8) &amp; 0xFF;    Buffer[2] = (BMXPFMSZ &gt;&gt; 16) &amp; 0xFF;    Buffer[3] = (BMXPFMSZ &gt;&gt; 24) &amp; 0xFF;        Buffer[4] = 0;    Buffer[5] = 1;    Buffer[6] = (DEVID &gt;&gt; 12) &amp; 0xFF;    Buffer[7] = 0;
 +
|-
 +
| BRC || Bootloader Read Code || S || 1 || UINT32 || - || address to read || 128 || UINT8 || - || data read starting at address || Reads a block of 128 bytes starting at specified address
 +
|-
 +
| BEC || Bootloader Erase Code || S || 1 || UINT16 || - || Page to erase || - || - || - || - || Erases the Flash page specified
 +
|-
 +
| BWC || Bootloader Write Code || S || 1 + 128 || UINT32 UINT8 || - - || address to write 128 bytes to write || - || - || - || - || Writes a block of 128 bytes starting at specified address
 +
|-
 +
| BWF || Bootloader Write conFig  || S || 24 || UINT8 || - || 24bytes of config data || - || - || - || - || This function is NOT implemented. Config Data for the CPU is part of the FBL and cannot be modified
 +
|-
 +
| BJA || Bootloader Jump Application || S/G || - || - || - || - || - || - || - || - || Jump to Application if the checksum is correct
 +
|-
 +
| ADD || ADDress request/set || G || 16 || UINT8<br/>UINT8 || - || <Serial_Number><br/><Seed> || The serial number of the sending module <br/>The random seed that the module will generate || - || - || - || This message is to announce the presence of the module, a S;ADD will be expected
 +
|-
 +
|  || || S || 17 || UINT8<br/>UINT8<br/>UINT8 || - || <Serial_Number><br/><Seed><br/><Addres> || The serial number of the receiving module <br/>The random seed that the module provied<br/>the new address to program into the module for this communication session || - || - || - || This is a response to a G;ADD request from the module in discovery mode.
 +
|}
 +
 +
 +
 +
 +
== Small detail on subset of commands ==
 +
 +
=== "DGT": Go to the discovery mode ===
 +
 +
The Energy bus can be put in 3 modes:
 +
* Normal mode: All communication is passed to the required modules
 +
* Addressing mode: The modules will notify the master when their button is pressed on the front panel.
 +
* discovery mode: The module will periodically send its serial number and wait for the response.
 +
 +
 +
;Request M->S
 +
{| class="wikitable sortable" border="1"
 +
| align="center" style="background:#f0f0f0;"|''''''
 +
| align="center" style="background:#f0f0f0;"|'''0'''
 +
| align="center" style="background:#f0f0f0;"|'''1'''
 +
| align="center" style="background:#f0f0f0;"|'''2'''
 +
| align="center" style="background:#f0f0f0;"|'''3'''
 +
| align="center" style="background:#f0f0f0;"|'''4'''
 +
| align="center" style="background:#f0f0f0;"|'''5'''
 +
| align="center" style="background:#f0f0f0;"|'''6'''
 +
| align="center" style="background:#f0f0f0;"|'''7'''
 +
| align="center" style="background:#f0f0f0;"|'''8'''
 +
| align="center" style="background:#f0f0f0;"|'''9'''
 +
| align="center" style="background:#f0f0f0;"|'''10'''
 +
| align="center" style="background:#f0f0f0;"|'''11'''
 +
|-
 +
| <code>STR</code>||ID0||ID1||CID||<code>S</code>||<code>D</code>||<code>G</code>||<code>T</code>||Length||Mode||CRC||13||10
 +
|}
 +
 +
* The ID0..1 is the destination slave address. Since this is a broadcast message, ID0 and ID1 must be set at 0xff.
 +
* CID=0
 +
* Byte3="S" -> Set
 +
* Byte4..6="DGT" -> Instruction
 +
* Length=1
 +
* Mode:
 +
** Mode=1 -> Put bus in Discovery Mode
 +
** Mode=0 -> Put bus in Normal Mode
 +
* CRC: CRC7 calculation of Byte0..8
 +
 +
=== "ADD": GET/SET address ===
 +
 +
This command will request or set an address for some serial number
 +
 +
;Request M->S
 +
{| class="wikitable sortable" border="1"
 +
| align="center" style="background:#f0f0f0;"|''''''
 +
| align="center" style="background:#f0f0f0;"|'''0'''
 +
| align="center" style="background:#f0f0f0;"|'''1'''
 +
| align="center" style="background:#f0f0f0;"|'''2'''
 +
| align="center" style="background:#f0f0f0;"|'''3'''
 +
| align="center" style="background:#f0f0f0;"|'''4'''
 +
| align="center" style="background:#f0f0f0;"|'''5'''
 +
| align="center" style="background:#f0f0f0;"|'''6'''
 +
| align="center" style="background:#f0f0f0;"|'''7'''
 +
| align="center" style="background:#f0f0f0;"|'''8..19'''
 +
| align="center" style="background:#f0f0f0;"|'''20..23'''
 +
| align="center" style="background:#f0f0f0;"|'''24'''
 +
| align="center" style="background:#f0f0f0;"|'''25'''
 +
| align="center" style="background:#f0f0f0;"|'''26'''
 +
| align="center" style="background:#f0f0f0;"|'''27'''
 +
|-
 +
| <code>STR</code>||ID0||ID1||CID||<code>S</code>||<code>A</code>||<code>D</code>||<code>D</code>||Length = 17||Serial_number||Seed||Address||CRC||13||10
 +
|}
 +
 +
* The ID0..1 is the destination slave address. Since this is a broadcast message, ID0 and ID1 must be set at 0xff.
 +
* CID=0
 +
* Byte3="S" -> Set
 +
* Byte4..6="ADD" -> Instruction
 +
* Length=17
 +
* Serial_number: The serial number of the module, 12 bytes
 +
* seed: Random seed number to avoid serial number clashes
 +
* address: The address to give to the module
 +
* CRC: CRC7 calculation of Byte0..8
 +
 +
 +
;Request S-> M
 +
{| class="wikitable sortable" border="1"
 +
| align="center" style="background:#f0f0f0;"|''''''
 +
| align="center" style="background:#f0f0f0;"|'''0'''
 +
| align="center" style="background:#f0f0f0;"|'''1'''
 +
| align="center" style="background:#f0f0f0;"|'''2'''
 +
| align="center" style="background:#f0f0f0;"|'''3'''
 +
| align="center" style="background:#f0f0f0;"|'''4'''
 +
| align="center" style="background:#f0f0f0;"|'''5'''
 +
| align="center" style="background:#f0f0f0;"|'''6'''
 +
| align="center" style="background:#f0f0f0;"|'''7'''
 +
| align="center" style="background:#f0f0f0;"|'''8..19'''
 +
| align="center" style="background:#f0f0f0;"|'''20..23'''
 +
| align="center" style="background:#f0f0f0;"|'''24'''
 +
| align="center" style="background:#f0f0f0;"|'''25'''
 +
| align="center" style="background:#f0f0f0;"|'''26'''
 +
|-
 +
| <code>STR</code>||ID0||ID1||CID||<code>S</code>||<code>A</code>||<code>D</code>||<code>D</code>||Length = 16||Serial_number||Seed||CRC||13||10
 +
|}
 +
 +
* The ID0..1 is the destination slave address. Since this is a broadcast message, ID0 and ID1 must be set at 0xff.
 +
* CID=0
 +
* Byte3="S" -> Set
 +
* Byte4..6="ADD" -> Instruction
 +
* Length=16
 +
* Serial_number: The serial number of the module, 12 bytes
 +
* seed: Random seed number to avoid serial number clashes
 +
* CRC: CRC7 calculation of Byte0..8
 +
 +
= Improvements to Energy bus =
 +
 +
Some improvements are needed for the energy bus to overcome issues regarding to addressing of modules, therefore a small itteration has been proposed for the energy modules to make this protocol more robust. The first version is compaired to the new version in the images below.
 +
 +
Current situation (V1.0)
 +
 +
[[file:EN_COMM_V1_PART_1.png | x1500px | none  ]]
 +
[[file:EN_COMM_V!_PART_2.png | x1500px | none  ]]
 +
 +
 +
 +
New version (V1.1)
 +
 +
[[file:EN_COMM_V2_part_1.png | x1500px | none ]]
 +
[[file:EN_COMM_V2_part_2.png | x1500px | none ]]
 +
[[file:EN_COMM_V2_part_3.png | x1500px | none ]]

Latest revision as of 15:43, 7 December 2022

General

GST : GeneralStatus

Gives back the general status of the module.

  • Input
    • none
  • Output
    • status: 1xBYTE status
      • todo explain the status values.

TON : TimeOn

Gives back the time in seconds the module is running.

  • Input
    • none
  • Output
    • time : 1xUINT32 time running [s]


FIV : FirmwareIDVersion

Gives back the firmware ID and version. Depending if the module is in application or in bootloader mode, an other value is returned.

  • Input
    • none
  • Output
    • ID and version: 16 chars (ex. "OMFPC_3_2_1" or "OMFBC_1_2_3")

Power

FST : FeedStatus

Gives back the status of each currentFeeds in the energymodule. Normally the status will always be the same per 2 feeds because the status is the one per chip which is per 2 feeds.

  • Input
    • none
  • Output
    • feedstatus : 12xUINT32
      • The bits in each UINT32 are described in the manual of CS5480 with keyword STATUS0

FCO : FeedCounter

Gives back the number of currentFeeds in the energymodule. this should be fixed to 12.

  • Input
    • none
  • Output
    • feedcount : UINT16 number of feeds [#]

VOL : Voltage

Gives back the voltages that the energymodule measure.

  • Input
    • none
  • Output
    • Voltage : 3xFLOAT [V]

FRE : Frequency

Gives back the frequencies that the energymodule measure for the different voltage channels.

  • Input
    • none
  • Output
    • Freqency : 3xFLOAT [Hz]

CUR : Current

Gives back the current that the energymodule measure.

  • Input
    • none
  • Output
    • Current : 12xFLOAT [A]

POW : Power

Gives back the real power that the energymodule measure.

  • Input
    • none
  • Output
    • Power : 12xFLOAT [W]

ENE : Energy

Gives back the energy that the energymodule calculate.

  • Input
    • none
  • Output
    • Energy : 12xINT32 [kWh]

or set the energy to a specific value

  • Input
    • Fixed value : 1 BYTE set to 0xAA
    • EnergySetValue : 12xINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
  • Output
    • none

EDA : EnergyDay

Gives back the energy that the energymodule calculate when the module is set to day mode (see [SDN : SetDayNight]).

  • Input
    • none
  • Output
    • EnergyDay : 12xINT32 [kWh]

or set the energy to a specific value

  • Input
    • Fixed value : 1 BYTE set to 0xAA
    • EnergySetValue : 12xINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
  • Output
    • none

ENI : EnergyNight

Gives back the energy that the energymodule calculate when the module is set to night mode (see [SDN : SetDayNight]).

  • Input
    • none
  • Output
    • EnergyNight : 12xINT32 [kWh]

or set the energy to a specific value

  • Input
    • Fixed value : 1 BYTE set to 0xAA
    • EnergySetValue : 12xINT32 [kWh] set to 48x 0x00 if you want to reset all the energies
  • Output
    • none

VST : VoltageSampleTime

Gives back 1 period of a voltage channel. The phase is locked to a positive zerocross of the voltage. The data is given back in 2 parts because the data is to big for 1 call.

  • Input
    • channel : 1 BYTE [0-11] : [0-3] = voltage A; [4-8] = voltage B; [9-11] = voltage C
    • part : 1xBYTE [0-1] select if you want the first or last 50 samples of the voltage
  • Output
    • voltageSamples : 50xFLOAT [V] gives back NaN values if 1 period is done.

VSF : VoltageSampleFreq

Gives back the frequencycomponents of a voltage channel.

  • Input
    • channel : 1 BYTE [0-11] : [0-3] = voltage A; [4-8] = voltage B; [9-11] = voltage C
    • numof : 1xBYTE [0-20] select the number of frequency components you want to get from that voltage channel
  • Output
    • voltageComponents : [numof]xFLOAT [V] : first is DC, second sample is first harmonic
    • PhaseComponents : [numof]xFLOAT [rad]

CST : CurrentSampleTime

Gives back 1 period of a current channel. The phase is locked on the corresponding voltage for that channel. The data is given back in 2 parts because the data is to big for 1 call.

  • Input
    • channel : 1 BYTE [0-11] current channel
    • part : 1xBYTE [0-1] select if you want the first or last 50 samples of the current
  • Output
    • currentSamples : 50xFLOAT [A] gives back NaN values if 1 period is done.

CSF : CurrentSampleFreq

Gives back the frequency components of a current channel.

  • Input
    • channel : 1 BYTE [0-11]
    • numof : 1xBYTE [0-20] select the number of frequency components you want to get from that current channel
  • Output
    • CurrentComponents : [numof]xFLOAT [A] : first is DC, second sample is first harmonic
    • PhaseComponents : [numof]xFLOAT [rad]

PowerSettings

ENM : EnergyMode

  • The energy level is calculated from the power in time.
  • Depending on the energy mode, when power is negative, the energy level can decrease, hold or increase its value, depending on the amount of power.
  • modes:
    • 0 = Hold the energy level fixed when there is negative power on the channel.
    • 1 = Increase the energy level (use the abs value)
    • 2 = Decrease the energy level

Gives back the energy mode

  • Input
    • none
  • Output
    • EnergyMode : 12xBYTE

or set the energy mode

  • Input
    • EnergyMode : 12xBYTE
  • Output
    • none

EPT : EnergyPowerThreshold

Energy is increased depending on the amount of power. To avoid very small power levels to increase the energy level, a threshold can be set as a minimum amount of power needed to increase the energy level.

Gives back the power threshold.

  • Input
    • none
  • Output
    • PowerThreshold: 1xfloat [W]

or set the power threshold.

  • Input
    • PowerThreshold: 1xfloat [W]
  • Output
    • none

SDN : SetDayNight

Set the EnergyModule in day or nightmode. This is used if different rates are used for day and night. This value can be set per feed.

  • Input
    • DayNight : 12xBYTE [night:0,day:1]
  • Output
    • none

SCI : SetCurrentInverse

Per channel you can specify if the current signal should be interpreted inverse or not. This is important to have the right sign of the power calculated per channel.

Set the current inverse mode.

  • Input
    • CurrentInverse: 12xBYTE [not inverse:0,inverse:1]
  • Output
    • none

CCF: CurrentClampFactor

  • Per channel a different current clamp can be connected.
  • The calibration values are done for a 50A clamp.
  • If you connect a different type of current clamp a compensation can be set via the CurrentClampFactor.
    • ex. for a 25A current clamp a factor of 0.5 can be set.

Set the CurrentClampFactor.

  • Input
    • ClampFactor: 12xFLOAT
  • Output
    • none

Calibration

SVO : SetVoltage

  • There are 3 voltage channels that can be calibrated.
  • The parameter should be the voltage connected to one or more of the voltage channels.
  • Only the channels that have a voltage above 10V (before calibration) will be calibrated. This way you can calibrate every channel separately or in one shot.
  • If the calibrated value deviate more than factor 2 (in both directions), the value will also be 'floored'.
  • [edit] Calibration of the voltage
  • Input
    • Voltage : 1xFLOAT [V]
  • Output
    • none

SDV : SetDefaultVoltage

Sets all the calibration values for the voltage channels to the default value

  • Input
    • none
  • Output
    • none

SCU : SetCurrent

  • There are 12 current channels that can be calibrated.
  • The parameter should be the current connected to one or more of the current channels. <<-- what with different current-sensors? should be calibrated with 1 current sensor and an extra parameter should be used to have an extra * factor to use in the calculation.
  • Only the channels that have a current above 0.1A (before calibration) will be calibrated. This way you can calibrate every channel separately or in one shot.
  • If the calibrated value deviate more than factor 2 (in both directions), the value will also be 'floored'.
  • Input
    • Current : 1xFLOAT [A]
  • Output
    • none

SDC : SetDefaultCurrent

Sets all the calibration values for the current channels to the default value

  • Input
    • none
  • Output
    • none

COF : CalibrationOffset

Addressing

AGT : AddressmodeGoTo

WAD : WantAnAddress

Sends the firmware ID and version (like in the FIV command). This is the only command that asynchronously can be send from a module when in address mode.

  • Output
    • ID and version: 16 chars (ex. "OMFPC_3_2_1")

SAD : SetAddress

Bootloader

BGT : BootloaderGoTo

Go to bootloader, to check if the module is in bootloader mode, you can ask FIV : FirmwareIDVersion and see if OMFBC... is given back in stead of OMFPC...

  • Input
    • none
  • Output
    • none

BEC : Bootloader Erase Code

  • Input
    • page address : 1xUINT16
  • Output
    • none

value between 6 and 63 (first 6 pages are bootloader)

one page is 4096 bytes so if you delete 1 page you have to do some BWC's to fill it up

BWC : Bootloader Write Code

Before doing a write make sure that an erase is done with BEC

  • Input
    • start address : 1 UINT32
    • Code : 32xUINT32 with data
  • Output
    • none

BJA : Bootloader Jump Application

Go back to app if code is valid (checksum is ok) ACK if jump to app will be preformed, REPLY_NAK_INTERNAL if not ok

  • Input
    • none
  • Output
    • none

Special

EEP : EEPROMdata

Gives back some EEPROM bytes from a certain address

  • Input
    • Address : 1xUINT16
    • Length : 1xUINT16
  • Output
    • Data : <Length>xBYTE data starting from position <Address>

or set some bytes to the EEPROM

  • Input
    • Address : 1xUINT16
    • DataBytes : 1..NxBYTE
  • Output
    • none

EEC : EEPROMcleardata

Clear some pages in the EEPROM

  • Input
    • Page : 1..NxBYTE : always starting from page 0 to page N-1. Only the pages where the corresponding byte is set to 0x01 will be cleared.
  • Output
    • none

PageInfo:

  • Page 0 = General data
  • Page 1 = Calibration data
  • page 2-3 = kWh data

RIC : RAWICCommand [Don't use]

Info on how and what to send , see: manual of IC CS5480

send something to a specific IC some data (set).

  • Input
    • ChipNumber: 1xBYTE
    • Bank : 1xBYTE
    • Data : 4xBYTE
  • Output
    • none

If you send a read command, the data can be retrieved via this get. If the data is not yet ready a NAK is send

  • Input
    • none
  • Output
    • Data : 4xBYTE

STA : GetStates

Get all states of the statemachines internally.

  • Only the first x bytes are used:
    • [0]=I2C_1.State I2C_STATE
    • [1]=I2C_3.State I2C_STATE
    • [2]=spiState SPI_STATE
    • [3]=buttonmode BUTTON_STATE
    • [4]=DFTState DFT_STATE
    • [5]=CalibState CALIB_STATE
    • [6]=OscPostProcessState OSC_POSTPROCESS_STATE
    • [7]=SPISendOscState SPI_SEND_OSC_STATE
    • [8]=OscState OSC_STATE
    • [9]=EnergyState ENERGY_STATE
    • [10]=SpiRmsState SPI_RMS
    • [11]=FRAMState FRAM_STATE
    • [12]=CommunicationStatus COMMUNICATION_STATUS
    • [13]=CommState TSTATES
    • [14]-[31]= Not used yet
  • Input
    • none
  • Output
    • Data : 32xBYTE

NOS : NumOfStartups

Get the number of cold or hot resets of the device

  • Input
    • none
  • Output
    • Data : 1xUINT32

ELN : ErrorListNumOf

Get the number of errors in the error list

  • Input
    • none
  • Output
    • Data : 1xUINT16

or clear the errorlist by sending a Set command.

  • Input
    • none
  • Output
    • none

ELA : ErrorListAt

Get error from the errorlist at place: address (0 = oldest, ErrorListNumOf or size of list = newest error in errorlist)

  • Input
    • address :
  • Output
    • errorcode : 1xBYTE type of error , see errorcodelist
    • errorlevel : 1xBYTE 0=highest
    • numOfOoccur : 1xUINT16 of errorcode type
    • timestamp : 1xUINT32 occurance of this error based on TON : TimeOn time
    • text : 24xCHAR error explained in string format (can contain values in string format)
  • errorcodelist:
    • ERROR_CODE_NO_FRAM_DETECTED=10
    • ERROR_CODE_NO_TOPPANEL_DETECTED=11
    • ERROR_CODE_NO_POWERIC_DETECTED=12
    • ERROR_CODE_ERROR_IN_FRAM=100
    • ERROR_CODE_ERROR_IN_TOPPANEL=101

Error codes

  • REPLY_ACK = 0
  • REPLY_NAK_INTERNAL = 1
  • REPLY_NAK_FUNCTION_NOT_KNOWN = 2
  • REPLY_NAK_INDEX_NOT_OK = 3
  • REPLY_OUT_OF_BOUNCE = 4
  • REPLY_NAK_NO_SET = 5
  • REPLY_NAK_NO_GET = 6
  • REPLY_NO_REPLY = 7





Command summary

Type Name mode Request count request type request unit request description response count response type response unit response description Comment
GST FUNC_GeneralStatus G - - - - 1 UINT8 - value 0xA5 dummy implementation
TON FUNC_TimeOn G - - - - 1 UINT32 s Time since on in seconds
NOS FUNC_NumOfStartups G - - - - 1 UINT32 - Startup count
FST FUNC_FeedStatus G - - - - 12 UINT32 - IC status for 12 channels
FCO FUNC_FeedCounter G - - - - 1 UINT16 - Number of channels
VOL FUNC_Voltage G - - - - 12 FLOAT V Actual RMS voltage
FRE FUNC_Frequency G - - - - 12 FLOAT Hz Actual frequency
CUR FUNC_Current G - - - - 12 FLOAT A Actual RMS current
POW FUNC_Power G - - - - 12 FLOAT W Actual power
RPO FUNC_ReactivePower G - - - - 12 FLOAT W Reactive power
ENE FUNC_Energy S 1 + 12 UINT8 FLOAT - kWh 0xAA EnergyTgt Total - - - - 0xAA start byte is qualifier for 12 floats following
G - - - - 12 FLOAT kWh EnergyActual Total
EDA FUNC_EnergyDay S 1 + 12 UINT8 FLOAT - kWh 0xAA EnergyTgt Day - - - - 0xAA start byte is qualifier for 12 floats following
G - - - - 12 FLOAT kWh EnergyActual Day
ENI FUNC_EnergyNight S 1 + 12 UINT8 FLOAT - kWh 0xAA EnergyTgt Night - - - - 0xAA start byte is qualifier for 12 floats following
G - - - - 12 FLOAT kWh EnergyActual Night
ENM FUNC_EnergyMode S 12 UINT8 enum mode - - - - 0 : ENERGY_DONT_ADD_WHEN_POWER_NEG 1 : ENERGY_ADD_WHEN_POWER_NEG 2 : ENERGY_SUBTRACT_WHEN_POWER_NEG
G - - - - 12 UINT8 enum mode
EPT FUNC_EnergyPowerThreshold S 1 FLOAT W target value - - - - Power values below this are ignored default is 0.1W
G - - - - 1 FLOAT W present value
EPT
FIV FUNC_FirmwareIDVersion G - - - - 12 string ascii Returns Program ID
SDN FUNC_SetDayNight S 1 UINT8 bool current state - - - - 0 : Night 1 : Day
SCI FUNC_SetCurrentInverse S 12 UINT8 bool target value determines whether sensor values are inverted or not 0 : Normal 1: Invert
G 12 UINT8 bool present value
CCF FUNC_CurrentClampFactor S 12 FLOAT - target value - - - - determines sensitivity of current sensors 1.0 for 50A current sensor 0.5 for 25A current sensor
G 0 - - - 12 FLOAT - present value
SVO FUNC_SetVoltage S 1 FLOAT V reference value 0 - - - All voltages are recalibrated to this level
S 1 + 1 BYTE FLOAT - V channel reference value 0 - - - All channels using the same VT are recalibrated to this level (0..3, 4..7, 8..11)
G - - - - 12 FLOAT - present value Returns raw calibration values. Default is 3.05e-5 which typically results in 290V
SCU FUNC_SetCurrent S 1 FLOAT A reference value - - - - ALL CURRENTS are recalibrated to this level. Make sure they all carry the reference current !
S 1 + 1 BYTE FLOAT - A channel reference value 0 - - - Only the specified channelis recalibrated to this level (valid 0..11)
G - - - - 12 FLOAT - present value Returns raw calibration values. Default for 50A/330mV sensor is 2.34e-6
SDV FUNC_SetDefaultVoltage S - - - - - - - - Sets the voltage calibrations to default which typically results in 290V
SDC FUNC_SetDefaultCurrent S - - - - - - - - Sets the current calibrations to default
SOS Func_SampleOffsets S - - - - - - - - Accepts present current and power readings as offset
SDO Func_SetDefaultOffset S - - - - - - - - Clears the current and power offsets
SPC FUNC_SetPhaseComp S 6 UINT32 - calculated values 0 - - - One value for each CS5480 on the board
G - - - - 6 UINT32 - values saved in calibration data One value for each CS5480 on the board
SCO FUNC_SetCurrentOffsets S 12 FLOAT A current offset - - - -
G - - - - 12 FLOAT A current offset
SPO FUNC_SetPowerOffsets S 12 FLOAT W power offset - - - -
G - - - - 12 FLOAT W power offset
COF FUNC_CalibrationOffset S - - - - - - - - Triggers current offset calibration Make sure no current flows through any sensor
G - - - - 12 FLOAT ? calibrated value Returns calibratedoffset values These ARE NOT USED by the application
VST FUNC_VoltageSampleTime G 1 1 UINT8 UINT8 - - channel part 50 FLOAT V series of voltage measurements Returns for the specified channel (0-11) a part (0-1) of the real-time VOLTAGE waveform.
VSF FUNC_VoltageSampleFreq G 1 1 UINT8 UINT8 - - channel number number FLOAT Hz? series of frequencies from Fourier Transform Returns for the specified channel (0-11) the specified number of frequencies resulting from an FFT on the VOLTAGE waveform
CST FUNC_CurrentSampleTime G 1 1 UINT8 UINT8 - - channel part 50 FLOAT V series of current measurements Returns for the specified channel (0-11) a part (0-1) of the real-time CURRENT waveform.
CSF FUNC_CurrentSampleFreq G 1 1 UINT8 UINT8 - - channel number number FLOAT dB? series of frequencies from Fourier Transform Returns for the specified channel (0-11) the specified number of frequencies resulting from an FFT on the CURRENT waveform
BGT FUNC_BootloaderGoTo S/G - - - - - - - - Performs a system reset, resulting in a jump to boot
RES FUNC_Hotresetthedevice S/G - - - - - - - - Performs a system reset, resulting in a jump to boot
AGT FUNC_AddressmodeGoTo S 1 UINT8 bool mode - - - - 0 : normal mode 1: address mode
WAD FUNC_WantAnAddress N/A - - - - - - - - Module will send "WAD" when it's put in addressmode. It shall never receive this command
GAD FUNC_GetAddress G - - - - 1 UINT8 bin module address also responds to ADDRESS 255 regardless the actual address
SAD FUNC_SetAddress S 1 UINT8 - module address - - - - Sent in response to a "WAD" request. Only accepted while module is in addressmode
S 1 +16 UINT8 UINT8 - Module address Module Serial nr. Sent to force change the address of the module. Only accepted in addressmode and with correct serial number.
SSN FUNC_SetSerialNumber S 16 UINT8 char serial number - - - -
G - - - - 16 UINT8 char serial number
SBO FUNC_SetBoardOptions S 4 UINT8 bin Board assembly info - - - - Byte0: UseCorrectedCCF - 0 = No, 1 = Yes Byte1: Boardtype - 0x52 for OMHEY5.2 Byte2: Assembly option1-2 - unassigned atm Byte3: EOLdataVer (read only - ignored in write)
G - - - - 4 UINT8 bin Board assembly info
WED FUNC_WriteEolDataToFlash S 4 UINT8 bin magic number 0xA55A7F80 - - - - Writes 256bytes of EOL data to flash page 0x1D00500
G - - - - 1 UINT8 bool status 0: EOL data not read from FLASH 1: EOL data read from FLASH
EEP FUNC_EEPROMdata S 1 var UINT16 UINT8 - - target address - - - - A variable number of BYTEs is written to EEPROM - mirror Address range 0x0000 - 0x07FF (2kB)
G 1 1 UINT16 UINT16 - - source address number number UINT8 - EEPROM data A variable number of BYTEs is read from the EEPROM mirror - Address range 0x0000 - 0x07FF (2kB)
EEC FUNC_EEPROMcleardata S var UINT8 bool list of pages - - - - this function expects a list of up to 8 bool values. The index selects the page to be cleared. The first value always maps to page 0. If the value == 1, the page is set to 0xFF e.g. 01110001 will clear pages 1,2,3 and 7
RIC FUNC_RAWICCommand S 1 1 1 UINT8 UINT8 UINT32 - - - IC index (0..5) bank (0..1) Command - - - - sends a raw command to one of the CS5480
G - - - - 1 UINT32 - Readback of last command
ELA FUNC_ErrorListAt G 1 UINT16 - errorNumber 32 UINT8 ErrorList[errorNumber] ERROR_CODE errorcode BYTE errorlevel//zero is highest prior UINT16 numOfOoccur UINT32 timestamp BYTE text[24];
ELN FUNC_ErrorListNumOf S - - - - - - - - Clears ErrorList
G - - - - 1 UINT16 - Number of errors
ERL FUNC_ErrorReportList G - - - - n UINT8 - List of up to 16 Errors List of errors which have occurred at least once since ELN S
STA FUNC_GetStates G - - - - 32 14 bytes, but 32 are sent - will contain rubbish states[0]=(BYTE)I2C_1.State; states[1]=(BYTE)I2C_3.State; states[2]=(BYTE)spiState; states[3]=(BYTE)buttonmode; states[4]=(BYTE)DFTState; states[5]=(BYTE)CalibState; states[6]=(BYTE)OscPostProcessState; states[7]=(BYTE)SPISendOscState; states[8]=(BYTE)OscState; states[9]=(BYTE)EnergyState; states[10]=(BYTE)SpiRmsState; states[11]=(BYTE)FRAMState; states[12]=(BYTE)CommunicationStatus; states[13]=(BYTE)CommState;
IND FUNC_Indicate S 1 UINT 8 bool Indicate state Indicate the module by the LED’s
BRI Bootloader Read chip ID G - - - - 8 UINT8 Flash Size Device ID Buffer[0] = BMXPFMSZ & 0xFF; Buffer[1] = (BMXPFMSZ >> 8) & 0xFF; Buffer[2] = (BMXPFMSZ >> 16) & 0xFF; Buffer[3] = (BMXPFMSZ >> 24) & 0xFF; Buffer[4] = 0; Buffer[5] = 1; Buffer[6] = (DEVID >> 12) & 0xFF; Buffer[7] = 0;
BRC Bootloader Read Code S 1 UINT32 - address to read 128 UINT8 - data read starting at address Reads a block of 128 bytes starting at specified address
BEC Bootloader Erase Code S 1 UINT16 - Page to erase - - - - Erases the Flash page specified
BWC Bootloader Write Code S 1 + 128 UINT32 UINT8 - - address to write 128 bytes to write - - - - Writes a block of 128 bytes starting at specified address
BWF Bootloader Write conFig S 24 UINT8 - 24bytes of config data - - - - This function is NOT implemented. Config Data for the CPU is part of the FBL and cannot be modified
BJA Bootloader Jump Application S/G - - - - - - - - Jump to Application if the checksum is correct
ADD ADDress request/set G 16 UINT8
UINT8		 - <Serial_Number>
<Seed>		 The serial number of the sending module
The random seed that the module will generate		 - - - This message is to announce the presence of the module, a S;ADD will be expected
S 17 UINT8
UINT8
UINT8		 - <Serial_Number>
<Seed>
<Addres>		 The serial number of the receiving module
The random seed that the module provied
the new address to program into the module for this communication session		 - - - This is a response to a G;ADD request from the module in discovery mode.



Small detail on subset of commands

"DGT": Go to the discovery mode

The Energy bus can be put in 3 modes:

  • Normal mode: All communication is passed to the required modules
  • Addressing mode: The modules will notify the master when their button is pressed on the front panel.
  • discovery mode: The module will periodically send its serial number and wait for the response.


Request M->S
' 0 1 2 3 4 5 6 7 8 9 10 11
STR ID0 ID1 CID S D G T Length Mode CRC 13 10
  • The ID0..1 is the destination slave address. Since this is a broadcast message, ID0 and ID1 must be set at 0xff.
  • CID=0
  • Byte3="S" -> Set
  • Byte4..6="DGT" -> Instruction
  • Length=1
  • Mode:
    • Mode=1 -> Put bus in Discovery Mode
    • Mode=0 -> Put bus in Normal Mode
  • CRC: CRC7 calculation of Byte0..8

"ADD": GET/SET address

This command will request or set an address for some serial number

Request M->S
' 0 1 2 3 4 5 6 7 8..19 20..23 24 25 26 27
STR ID0 ID1 CID S A D D Length = 17 Serial_number Seed Address CRC 13 10
  • The ID0..1 is the destination slave address. Since this is a broadcast message, ID0 and ID1 must be set at 0xff.
  • CID=0
  • Byte3="S" -> Set
  • Byte4..6="ADD" -> Instruction
  • Length=17
  • Serial_number: The serial number of the module, 12 bytes
  • seed: Random seed number to avoid serial number clashes
  • address: The address to give to the module
  • CRC: CRC7 calculation of Byte0..8


Request S-> M
' 0 1 2 3 4 5 6 7 8..19 20..23 24 25 26
STR ID0 ID1 CID S A D D Length = 16 Serial_number Seed CRC 13 10
  • The ID0..1 is the destination slave address. Since this is a broadcast message, ID0 and ID1 must be set at 0xff.
  • CID=0
  • Byte3="S" -> Set
  • Byte4..6="ADD" -> Instruction
  • Length=16
  • Serial_number: The serial number of the module, 12 bytes
  • seed: Random seed number to avoid serial number clashes
  • CRC: CRC7 calculation of Byte0..8

Improvements to Energy bus

Some improvements are needed for the energy bus to overcome issues regarding to addressing of modules, therefore a small itteration has been proposed for the energy modules to make this protocol more robust. The first version is compaired to the new version in the images below.

Current situation (V1.0)

EN COMM V1 PART 1.png
EN COMM V! PART 2.png


New version (V1.1)

EN COMM V2 part 1.png
EN COMM V2 part 2.png
EN COMM V2 part 3.png
Retrieved from "https://wiki.openmotics.com/index.php?title=Energy_Module_Commands&oldid=8829"