Powered by Redocly

/ctid

This service provides access to the CTid® facility built into the EG4xxx series meters. Specifically, it enables:

  1. retrieving the CTid® information from a sensor,

  2. flashing the (optional) locator LED on the sensor, and

  3. deleting the stored CTid® information associated with a sensor port.

Note that while scanning or flashing a sensor, normal measurement of local sensors is suspended. It is therefore recommended to use this service primarily during device setup.

All methods other than GET required a user with the save right.

Python Example

A Python program illustrating the use of this service can be found here. This program takes advantage of class egauge.webapi.device.CTidInfo to handle the details of encoding the HTTP requests and decoding the responses.

Get all CTid® information

Read the existing (previously scanned) CTid® info of all sensor ports.

SecurityApiKey
Responses
200

CTid® information response.

401

Unauthorized response.

get/ctid
Request samples 
Response samples 
application/json
{
  • "info": [
    ]
}
Replace saved CTid® info of several sensors
Write CTid® info of the sensor ports specified in the request
body to the meter.  This does not update the CTid® info on the
sensors themselves.


This method is supported mainly for testing purposes.  However,
it could also be used to fix faulty or inaccurate sensor
information.  The written information will persist only until
the sensor ports are scanned again, so this would only be a
temporary fix.


SecurityApiKey 
Request 
Request Body schema: application/json
Array of objects (CTidInfoObject) 
 
Responses 
200
CTid® information response.


401
Unauthorized response.


put/ctid
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
Get CTid® info of a port
Read the CTid® info of a sensor port or get the status of an
operation that is in progress.


Without a query parameter, this returns the CTid® info object of
the most recent scan.  If the port has not been scanned or the
scan failed, an empty object is returned instead.


If the tid query parameter is specified, it must be the
transaction id of a CTid® operation that was previously
initiated on this port.  A status object is returned if the
operation identified by tid is still in progress.  Otherwise,
the request is handled as if tid had not been specified.


SecurityApiKey 
Request 
path Parameters
port
required
integer  >= 1 
The port number to apply this request to.


 
query Parameters
tid
integer  >= 0 
The transaction id of the CTid® operation to return
information on.


 
Responses 
200
CTid® information response.


401
Unauthorized response.


get/ctid/{port}
Request samples 
Response samples 
application/json
{
  • "ts": "1668455577",
  • "tid": 2008264382,
  • "port": 2,
  • "polarity": "+",
  • "version": 2,
  • "mfgid": 0,
  • "model": "ERA",
  • "sn": 2,
  • "k": 2,
  • "rsrc": 176,
  • "rload": 10000000,
  • "params": {
    }
}
Initiate CTid® operation on a port
Initiate the operation specified in the request body.  EG4xxx
series meters are limited to performing one CTid® operation at a
time.  If this request is received while another operation is
pending, an error is returned.


SecurityApiKey 
Request 
path Parameters
port
required
integer  >= 1 
The port number to apply this request to.


 
Request Body schema: application/json
op
required
string
The operation to be initiated:


    

  • flash: Start blinking the locator LED on the
  sensor.
    

    • 

  • scan: Start scanning the sensor's CTid®
  information.  A scan typically takes one to
  five seconds.  If the scan is successful, the
  resulting information is stored on the meter.
    

    • 



 Enum: "flash" "scan"  
polarity
required
string
The voltage polarity with which to initiate the
operation.  A plus sign (+) requests positive
polarity, a minus sign (-) requests negative
polarity.


For operation scan, positive polarity should
succeed unless the sensor is miswired.  Thus, it is
usually best to attempt scanning first with positive
polarity and, if that fails, retry with negative
polarity.


For operation flash, either polarity will cause
the locator LED to blink, albeit with different
blink frequency.  For a correctly wired sensor,
negative polarity should be used for blinking.  If
this operation is not stopped explicitly, it will
time out automatically after about 30 minutes.


 Enum: "+" "-"  
tid
required
integer  [ 0 .. 4294967295 ] 
The transaction id to use for the operation.  This
should be a randomly-chosen integer that uniquely
identifies the operation to be initiated.  The
client can later check on the status of the
operation by passing this number as the tid query
parameter to a GET request on this resource.


 
Responses 
200
CTid® post response.


401
Unauthorized response.


post/ctid/{port}
Request samples 
application/json
{
  • "op": "flash",
  • "polarity": "+",
  • "tid": 4294967295
}
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
Replace saved CTid® info of the port
Write CTid® info of the sensor port.  This replaces any existing
CTid® info on the meter with the one passed in the request body.
It does not update the CTid® info on the sensor itself.


This method is supported mainly for testing purposes.  However,
it could also be used to fix faulty or inaccurate sensor
information.  The written information will persist only until
the sensor port is scanned again, so this would only be a
temporary fix.


SecurityApiKey 
Request 
path Parameters
port
required
integer  >= 1 
The port number to apply this request to.


 
Request Body schema: application/json
error
string (ErrorString) 
A message describing the first error that occurred.  This
member is present only if an error occurred.


 
k
integer  >= 0 
The type of the sensor (kind).


 
mfgid
required
integer  >= 0 
The numeric identifier of the manufacturer of the sensor.


 
model
required
string
The model name of the sensor.


 
object
Sensor-type dependent parameters.


 
polarity
string
The polarity of the voltage that was used to read this info.


 Enum: "+" "-"  
port
required
integer  >= 1 
The port number this information is associated with.


 
rload
number
The load resistance that was applied when characterizing the
other parameters of this sensor.


 
rsrc
number
The output resistance of the sensor.


 
sn
required
integer  [ 0 .. 16777215 ] 
The serial number of the sensor.


 
tid
required
integer  >= 0 
Transaction ID of the scan that initiated the reading of this
information.


 
ts
required
string (ForeverStamp) 
The Unix timestamp of when the
information was scanned.


 
version
integer  >= 0 
The CTid protocol version that the sensor implements.


 
Responses 
200
CTid® put response.


401
Unauthorized response.


put/ctid/{port}
Request samples 
application/json
{
  • "ts": "1668455577",
  • "tid": 2008264382,
  • "port": 2,
  • "polarity": "+",
  • "version": 2,
  • "mfgid": 0,
  • "model": "ERA",
  • "sn": 2,
  • "k": 2,
  • "rsrc": 176,
  • "rload": 10000000,
  • "params": {
    }
}
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
Delete CTid® information of the port
Delete the CTid® info associated with the port from the meter.
This also terminates any pending scan or flash operations.


The CTid® info stored in the sensor is not affected by this
operation.


SecurityApiKey 
Request 
path Parameters
port
required
integer  >= 1 
The port number to apply this request to.


 
Responses 
200
CTid® delete response.


401
Unauthorized response.


delete/ctid/{port}
Request samples 
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
Stop any pending CTid® operation
Immediately stop any pending scan or flash operation.
Generally, this should be used only after successfully
initiating a flash operation as scan operations will stop
automatically after a few seconds.


SecurityApiKey 
Responses 
200
CTid® stop response.


401
Unauthorized response.


post/ctid/stop
Request samples 
Response samples 
application/json
{
  • "status": "OK",
  • "error": "Error message (present if an error occurred)."
}
➔ Next to /ctrl