How to use the API

The Line Test API can be used to troubleshoot problems with Chorus products.

The table below outlines how different parts of the Line Test API operate, and how each part can be used.

Line Test API Aspect	How it works	What it can be used for
Get Product information	Retrieves Product and Service inventory for a given product identifier.	Determine if the details of a given Chorus product correspond to your records. Details may include port details, service variant / plan, and location identifier.
Run and retrieve ONT Status test	Queries the ONT status.	Determine the current status of the ONT as part of customer diagnostics. Use the current status together with business rules to determine whether a Chorus Layer 1 fault should be raised.
Run and retrieve ONT Status over Time test	Provides the ONT status and Optical Signal Level history for the last 21 Days.	Determine if there is a trend in the service behaviour (for example, degradation) by observing the behaviour of the ONT over time.
Run and retrieve RGW Bandwidth test	Provides information about connectivity between service consumer's device and the Chorus ONT as well as traffic passed both to and from the ONT into/from the Chorus network.	Determine if connectivity issues exist between service consumer's device and the Chorus ONT as well as aiding in the diagnosis of layer 2 connectivity issues.
Retrieve Optical Information test	Provides the results of the optical information for the circuit when it was tested by the technician.	Determine whether the optical power was within the allowed range for the connection, along with the ONT Status at the time the circuit was tested by the technician.

Fibre

ONT Status

The table below provides the meaning of different information returned from the Line Test API.

Status

Description

Determined By

Additional Guidance

good

Indicates that there is no fault with ONT physical connectivity on the Chorus Network.

We expect no impact to end customer services.

Healthy optical signal quality.

Optical signal within range of reference result for this connection.

Absence of errors (bit / transmission errors).

Null

reduced

Indicates that the optical signal power is lower than historical.

This is not expected to impact the end customer service experience.

Optical signal is lower than historical reference for this connection.

Absence of errors (bit / transmission errors).

The lower optical signal level is unlikely to be impacting the end customer's service as it is highly likely that the optical level will remain within the overall service specification.

Changes in optical signal level could be related to:

Changes in network topology since the reference was created.
Addition of splices, attenuators or connectors to the network.
Slight changes in the physical fibre, for example, a small bend may have occurred into the fibre. Slight bends in fibre cables can cause the optical signal levels to decrease.

If bit / transmission errors are detected the status will change to a degraded service, indicating that services are likely to be impacted.

Please note that sending a Technician to resolve the optical signal problems for a connection in a reduced status may not always rectify any issue the user is experiencing.

degraded

Indicates that errors are detected.

The end customer experience may be impacted in a number of different ways.

Tier 1 troubleshooting must be completed before logging a fault.

This status suggests that bit/transmission errors are occurring on this connection, and these errors may impact the end customer's service.

The most common reasons for this status are:

A tight bend or kink has been put in the fibre cable.

Connectors on the fibre cable are dirty or damaged.

The end customer's service may or may not be directly affected by these errors.

We recommend that the checks are performed to ensure any issues the end customer is experiencing are linked to this line condition and not a secondary fault, for example, check when the end customer started experiencing the problem and compare this date to the ONT status over time to see if these match.

Resolving the ONT status may not always rectify the issue the user is experiencing. Further end-to-end troubleshooting may be required.

interrupted

A loss of connectivity to the ONT has been detected impacting the end customer's service.

Please ensure the ONT is powered on prior to logging a fault.

Most common reasons for this status:

A break in the fibre cable, usually between the splitter and the ONT.
Degraded or damaged connector on the fibre cable.
Unplanned network event.
Failure of the ONT power supply.

Please ensure that the ONT is powered on. If not please isolate the problem to the ONT power supply by testing alternative devices on the same socket.

Please note that repairs to power sockets on the property must be undertaken by the end customer's own electrician.

The ONT should always be plugged directly into the power socket.

switched_off

This status indicates that the end customer has turned off their ONT.

Ask the end customer to power on the ONT.

This status appears when the end customer has powered down their ONT.

This is triggered by a dying gasp alarm being received by the OLT.

Please remind the end customer NOT to turn off the ONT as this impairs our ability to accurately monitor and diagnose any reported faults.

unknown

This status indicates that the Fibre Test Tool is unable to poll the ONT at this time.

Use the ONT lights and CPE device statistics to identify if there is a fault.

The most common reasons for this status are:

The collector is unable to retrieve information from this ONT/OLT at this time
In rare instances this could be due to a loss of the OLT

When the collector is unable to poll the ONT, the ONT could be in any status ranging from in-service to interrupted.

We recommend checking your Unplanned Event Notifications.

If there is no outage for this OLT please troubleshoot using the lights on the ONT to determine if there is a fault within the Chorus Network.

ONT Status Over Time

The ONT Status Over Time is determined by one hour polls that are run for all ONTs on the Chorus Network. Different ONTs will be polled at different times. At the time of polling the tool will assess the optical signal quality. The tool will also check if errors have occurred within that hour, to determine the overall status for that hour.

As these statuses are determined by a poll once an hour - the assumption is that the status did not change within that hour. This means that short events (for example, a short drop in optical signal power that would be enough to change the status) is not reflected within this test. Additionally, if the ONT is down at the time of capture, then it is assumed to have been down from the time of the previous poll until the time of the current poll, regardless of the actual down time.

RGW Bandwidth

The RGW Bandwidth results are determined by measuring the traffic passing over the ONT which provides service for your product instance.

There may be other RSPs consuming ports on the same ONT which is used to provide your service. For these services you will be able to see which port is in use by the other service and if a device has been connected to these ports. This information is provided to alert staff conducting troubleshooting that other services are present on this ONT. Care should be taken to ensure that these other services are not disrupted during the troubleshooting process. Note: Traffic information for these other services is not provided.

BBIP – NBLT SLT and ELT.

Single line test (SLT) - Tests the condition of a single copper pair.

Electrical loop test (ELT) - Tests the copper line from the voice (NPOT) card in the ISAM / DSLAM to your customer and back.

If the response in either SLT or ELT tests contains the errorDetails object (within the results object), this indicates that the test could not be completed correctly and the diagnostics shown may be inaccurate. This could occur if another test is being run simultaneously on the same line. If this occurs, re-run the test to get accurate results and diagnostics. No faults should be raised if a test result contains the errorDetails object because the results in the response may not be accurate.

Measurement	Description	Fault State
Foreign DC voltage	To measure the foreign DC voltage, the line is disconnected from the battery and the residual DC voltage on the line is measured. Under normal on-hook conditions, there should not be a DC voltage on the line. Any residual voltage measured might be due to the offset of the measurement tool. A DC voltage might be measured on the line if a wire touches the ring wire of another pair (this is called a wire cross problem). If this is the case, the defected wire is not insulated anymore from the battery and a DC voltage between 0 and 48V might be measured.	Normal = 0. Above 6V is abnormal. Above 135 V is hazardous.
Foreign AC voltage[a]	Under normal conditions, when the phone is on-hook, there should be no AC voltage on the line. If an AC voltage is measured, a leakage from the electrical network to the phone line might be the root cause.	Normal = 0. Above 6Vrms is abnormal. Above 50Vrms is hazardous.
DC current	Under normal conditions, when the phone is on-hook, there should be no DC current on the line. If a DC current is measured, a leakage to the earth or to another pair is the likely cause, probably due to an insulation fault of the cable.	Normal = 0 when the phone is on the hook.
AC current	Under normal conditions, when the phone is on-hook and the phone is not ringing, there should be no AC current on the line. If an AC current is measured, a leakage from another pair can be the cause, probably due to an insulation fault of the cable.	Normal = 0 when the phone is on the hook and not ringing.
Insulating resistance	When the phone is on-hook, no DC current should flow through the line. The insulating resistance must be very high (several MOhm). A smaller value indicates an insulation fault. The insulating resistance can be measured by injecting a DC current in the wire, either from the tip wire to the ring wire or vice versa. If both tests give different values, a non-linear resistance is found. This might be due to oxidation phenomena between the wires (an oxidation layer can act as a semiconductor junction similar to a diode). Using this principle, this test can also be used to detect a special termination made of a diode. The termination detection is as follows: The insulating resistance is measured between tip-and-ring, tip-and-ground, ring-and-ground, tip-and-battery, and ring-and-battery. (The TIP-to-Battery and Ring-to-Battery resistances are computed from tip-ground, ring-ground and batter-ground resistance measurements.) The battery refers to the –48V reference of the battery.	Below 20K Ohms indicates an issue.
Insulating resistance BAT	Battery Resistance. If under 150 kOhm indicates a possible fault.
Capacitance	For an open line (that is, when there is no phone connected to the line), the capacitance is proportional to the line length (roughly 50nF/km). This is valid for the tip-ring capacitance as well as for both tip-ground and ring-ground capacitances. When a phone is connected, the ringer capacitance is in parallel with the loop (the ringer resistance can be neglected) so, the tip-ring capacitance strongly increases, up to a few F. The phone does not affect the ring-ground and tip-ground capacitances. Hence the loop length can still be estimated from the ring-ground and tip-ground capacitances. Strongly asymmetric ground capacitances might indicate that one of the two wires is open.	No phone connected: +/- 50nF per km of copper. Phone connected +> x nF. Imbalanced A-G & B-G indicates an issue. The results across all columns should be the same or similar. If not – likely to be moisture in the cable.
Noise level	This is the noise power measured in the audible bandwidth, so-called psophometric noise. It is expressed in dBmp (p stands for psophometric) where 0 dBmp corresponds to a power of 1mW within the audible bandwidth. For normal loops, for a line terminated by an on-hook phone, the psophometric noise should be below -65dBmp. When the phone is off-hook (but the mic is disabled), a slight increase can be accepted. A value of -60dBmp is usually tolerated. A value that is too high might indicate an excessive amount of crosstalk, resulting from a capacitive unbalance. It might also indicate a fault in the grounding of the central office or binder. The binder shield should be connected to earth at regular distances, typically every 500m. A lack of proper grounding usually translates into a 50Hz or 60Hz audible hum on the phone.	Should be below -50dBm.
Line impedance	The line impedance is computed from both the insulating resistance and the capacitance. The measured resistance and capacitance are considered to be in parallel.	N/A

Test result examples.

Name	Description	Repair Advice
Hazardous AC potential between tip (A) and ground (G)	1 An external, and possibly dangerous, voltage has been measured on the line between tip (A) and ground (G).	Check for insulation defect with electrical power network.
Hazardous AC potential between ring (B) and ground (G)	2 An external, and possibly dangerous, voltage has been measured on the line between ring (B) and ground (G).	Check for insulation defect with electrical power network.
Hazardous DC potential between tip (A) and ground (G)	3 An external, and possibly dangerous, voltage has been measured on the line between tip (A) and ground (G).	Check for insulation defect with electrical power network.
Hazardous DC potential between ring (B) and ground (G)	4 An external, and possibly dangerous, voltage has been measured on the line between ring (B) and ground (G).	Check for insulation defect with electrical power network.
Negative Hazardous DC potential between tip (A) and ground (G)	5 An external, and possibly dangerous, voltage has been measured on the line between tip (A) and ground (G).	Check for insulation defect with electrical power network.
Negative Hazardous DC potential between ring (B) and ground (G)	6 An external, and possibly dangerous, voltage has been measured on the line between ring (B) and ground (G).	Check for insulation defect with electrical power network.
Foreign AC electromotive force between tip (A) and ground (G)	7 An external voltage has been measured on the line between tip (A) and ground (G).	Check for crossed wires (insulation defect between different pairs).
Foreign AC electromotive force ring (B) and ground (G)	8 An external voltage has been measured on the line between ring (B) and ground (G).	Check for crossed wires (insulation defect between different pairs).
Foreign DC electromotive force between tip (A) and ground (G)	9 An external voltage has been measured on the line between tip (A) and ground (G).	Check for crossed wires (insulation defect between different pairs).
Foreign DC electromotive force between ring (B) to ground (G)	10 An external voltage has been measured on the line between ring (B) and ground (G).	Check for crossed wires (insulation defect between different pairs).
Negative Foreign DC electromotive force between tip (A) and ground (G)	11 An external voltage has been measured on the line between tip (A) and ground (G).	Check for crossed wires (insulation defect between different pairs).
Negative Foreign DC electromotive force between ring (B) to ground (G)	12 An external voltage has been measured on the line between ring (B) and ground (G).	Check for crossed wires (insulation defect between different pairs).
Resistive fault between tip (A) and ground (G)	13 Insufficient insulation has been detected on the cable between tip (A) and ground (G).	Repair the cable.
Resistive fault between ring (B) and ground (G)	14 Insufficient insulation has been detected on the cable between ring (B) and ground (G).	Repair the cable.
Resistive fault between tip (A) and ring (B)	15 Insufficient insulation has been detected on the cable between tip (A) and ring (B).	Repair the cable.
Capacitive unbalance due to high capacitance between ring (B) and ground (G)	The capacitive balance is not sufficient due to high capacitance between ring (B) and ground (G).	Check for water in the cable, bad contact or one-wire open fault.
Capacitive unbalance due to high capacitance between tip (A) and ground (G)	The capacitive balance is not sufficient due to high capacitance between tip (A) and ground (G).	Check for water in the cable, bad contact or one-wire open fault.
Cable not shielded or line too short	The line is either too short or the cable is not shielded or the cable shield is not correctly connected to earth. Loop length estimation and termination detection might not be reliable.	Check cable shielding and grounding.
Leakage fault between tip (A) and ground (G)	High resistance path has been detected on the cable between tip (A) and ground (G).	Check for water in the cable or repair the cable.
Leakage fault between ring (B) and ground (G)	High resistance path has been detected on the cable between ring (B) and ground (G).	Check for water in the cable or repair the cable.
Leakage fault between tip (A) and ring (B)	High resistance path has been detected on the cable between tip (A) and ring (B).	Check for water in the cable or repair the cable.

DSL – LSD and LQD

Line state diagnosis (LSD) – Test the current state of a DSL connection.

Line quality diagnosis (LQD) – Test the quality and state of a DSL connection over time. The results for the LQD test are stored within the Chorus backend systems for 30 days before being purged. Any LQD tests older than 30 days will only return the metadata associated with the test. When using Get Tests (historical tests) any LQD tests present in the result will also only return the metadata associated to that test regardless of the time since the test was completed. Full test results will only be returned when using Get Test using the Test ID for the LQD.

Field	Description
Inspection ID	System inspection identifying number.
cpeType	The type of Customer Premise Equipment.
dslType	The type of digital subscriber line. Example: adsl2plus = fibre to the node operating mode. Non Shdsl = not single pair high speed subscriber line. Line type pots = this is the type of access to the home. Latency interleaved = will be either interleaved or non-interleaved.
lineID	Identifies the exchange and the DSLAM that the internet services supplied by.
spectrumProfileName	Identifies configuration parameters of the spectrum profile (operating mode: ADSL / ADSL2, noise margin, PSD / Power, masking, and so on).
serviceProfilename	Identifies configuration parameters of the service profile (interleaving on or off, up and down speeds (full speed/full speed, or full speed/12bkps).
serviceTemplateName	Identifies the service associated with the DSLAM.
modemVendorid	Unique vendors modem ID.
systemVendorid	Unique system vendors modem ID.
systemVendorModel	Unique system vendors modem model ID.
serialNumber	Unique serial number of vendors modem.
serviceStability	Provides information to determine service stability (stable, unstable, unknown).
lineStatus	If the line status is: Down, look at the information returned in the fields in the Diagnosis Results section. Up, this means that DSLAM and modem are in sync, however, the CPE may have interoperability issues, for example, stability, rate impact.
Description	A plain english description of the diagnosis.
Impact	Identifies the impact that is occurring.
Confidence	Provides a degree of confidence in relation to the description.
relativeCapacityOccupation	Identifies the relative capacity occupation percentage.
attenuation	Identifies the amount of loss seen on the line and is affected by length of cable between the customer and equipment, the gauge [thicker = less loss], damage to the cable and such issues as multiples and so on.
loopAttenuation	The measured difference in the total power transmitted and the total power received over all subcarriers during diagnostics mode and initialization. It is measured in dB. It is only available for xDSL-managed lines, that is, ADSL2(+), VDSL, and VDSL2 lines.
noiseMargin	Identifies the noise margin which decreases as a result of the distance, line conditions and so on.
actualPsd	This is the actual power spectral density associated with the service (dBm/Hz).
outputPower	Identifies the power output value associated with the service.
userTraffic	Estimation of the ATM traffic rate. Very inaccurate (if shown at all) for LSD.
actualBitrate	Identifies the throughput bitrate specified in the profile. Allocated to the service.
attainableBitrate	Identifies the attainable bitrate the line can achieve, determined mainly by the attenuation and the noise margin.
impulseNoiseProtection	The actual negotiated number of symbols of Impulse Noise Protection.
interleavingDelay	The actual negotiated time in milliseconds for interleaving.
actualExpectedThroughput	The expected throughput (ETR) figure is a fixed value determined during initialisation. It represents the data rate available to the higher layers when noise conditions correspond to the values defined in the RTX configuration, that is, the net data rate minus the RTX overhead provisioned for retransmissions. Hence, it is not guaranteed to have a throughput of ETR all the time, as this depends on the noise conditions. In absence of impulse noise, the throughput reaches the net data rate. In case of really bad impulse noise conditions, the throughput might decrease below ETR. Only displayed on FD ISAM models.
actualNetDataRate	The actual net data rate (NDR) is the throughput available toward the higher layers when no retransmission occurs; in other words, the full rate of the line when no overhead is used for retransmission. Only displayed on FD ISAM models.
attainableExpectedThroughput	Estimation of the maximum achievable expected throughput at the DSL layer for the given loop conditions. Only displayed on FD ISAM models.
attainableNetDataRate	Estimation of the maximum achievable net data rate for the given loop conditions. Only displayed on FD ISAM models.
actualInpShine	Actual impulse noise protection against SHINE. Only displayed on FD ISAM models.
actualInpRein	Actual impulse noise protection against REIN. Only displayed on FD ISAM models.
lqd.parameter.actual.rtx.delay	Actual delay used on the line for retransmissions. Only displayed on FD ISAM models.
Per Band Line Parameters	This table displays parameters for each ADLS / VDSL band.

Further LQD

Interpret the results

Field	Description
Event Info	See Event Info below.
Monitored parameters	These results provide the Min (minimal), Max (maximum), Mean (average) and the StdDev (standard deviation) measurements in relation to the up and down stream values with the broadband services.

Event Info

Field	Description
spontaneousResyncs	The number of xDSL line resynchronisation events. These can be due to line issues, modem reboots or port resets.
failedInit	This is a spontaneous resync which fails. Failure is described as a resynchronisation event that takes too long, longer than expected or is actually multiple back-to-back resyncs.
Bitswaps	The number of bits swapped between tones. Note that this is a normal DSL event, these will almost always be a number here, but there is no action required.
profileSwitches	The number of profile switches, typically due to DLM.
collectionFailures	The number of times that the Network Analyser could not collect from the ISAM. This is due to some kind of management network issue and will show up in the graphs too. It is not specific to the customer's DSL line.
loopDiagnostics	Number of times Loop Diagnostics were run while the LQD was running.
upshiftRateAdaptationsDSEvents	Number of Seamless Rate Adaptation (SRA) events during the LQD inspection. This is used as part of the G.INP functionality.
downshiftRateAdaptationsDSEvents	Number of Seamless Rate Adaptation (SRA) events during the LQD inspection. This is used as part of the G.INP functionality.
upshiftRateAdaptationsUSEvents	Number of Seamless Rate Adaptation (SRA) events during the LQD inspection. This is used as part of the G.INP functionality.
downshiftRateAdaptationsUSEvents	Number of Seamless Rate Adaptation (SRA) events during the LQD inspection. This is used as part of the G.INP functionality.

API Developers