PTW UNIDOS webline User manual

User Manual
UNIDOSwebline
Interfaces
D776.131.01/02
2009-09 Sa

UNIDOSwebline Interfaces
Contents
2 D776.131.01/02
Contents
Contents 2
1Safety Information 3
2Interface Configuration 4
2.1 RS232 Interface 4
2.2 Ethernet Interface and UDP 5
3Interface Commands 6
3.1 Principles of Computer Communication 6
3.2 Command Structure 6
3.3 A Sample Session 7
3.4 Command Categories 7
4Commands by Functions 8
4.1 Notes on Command Overview 8
4.2 General Commands 9
4.3 Status Request and Diagnosis 11
4.4 Measurement and Control Commands 13
4.5 Data Base Commands for Detectors 18
4.6 Data Base Commands for User Settings 23
4.7 Statistics Commands 27
5Alphabetical Command List 31
6Error Messages 32

UNIDOSwebline Interfaces
Safety Information
D776.131.01/02 3
1 Safety Information
CAUTION
Improper handling.
Bodily Injury! Equipment damage!
This document is a supplement to the
UNIDOSwebline user manual and is valid only in
conjunction with that manual.
The safety statements appearing in the indicated
user manuals are applicable and must be ob-
served.
WARNING
Electricity is a source of risk, particularly when
the product is not in perfect operating condition
or when it is operated inappropriately.
Shock Hazard!
In addition to these safety statements, please
note that devices connected to the interface de-
scribed in this manual must fulfill the require-
ments of the standard IEC 60950-1.
PTW-FREIBURG
Physikalisch Technische Werkstätten
Dr. Pychlau GmbH
Lörracher Str. 7
79115 FREIBURG
GERMANY
Phone: [phone]
Fax: [phone]
[email protected]
www.ptw.de

UNIDOSwebline Interfaces
Interface Configuration
4 D776.131.01/02
2 Interface Configuration
2.1 RS232 Interface
The serial interface of the UNIDOSwebline is a RS232
interface with the following configuration:
Baud rates: 1200, 2400, 4800, 9600,
14400, 19200, 38400, 57600
or 115200 (adjustable)
Code: 8 data bit
Stop bit: 1 stop bit
Parity: none
Connector “SERIAL”: SUBD-connector, 9-pole,
female
The RS232 interface is electrically isolated from the
measuring device.
The RS232 interface is of DTE type (data terminal
equipment), e.g., UNIDOSwebline sends on TxD and
drives RTS.
For connections from UNIDOSwebline to the PC with
a standard 9 pin connector, use PTW cable
L178012 (2 m), L178026 (5 m) or T22373/K67-30
(30 m).
For connections to a standard 25 pin connector use
a gender changer additionally or the PTW cable
T22373/K49.
It is possible to work either with or without hardware
handshake.
For information only:
If the RS232 interface is at the quiescent state, the
voltage measured at TxD is ≤-5 V with reference to
GND.
Pin assignment and connection to a 9-pole or 25-pole connector with ‘standard IBM layout’:
UNIDOSwebline
9-pole
IBM
9-pole
IBM
25-pole
Pin-No. Signal Type Pin-No. Pin-No. Signal Type
1 no connection ↔1 1 shield
2 TxD output →2 3 RxD input
3 RxD input ←3 2 TxD output
4 DTR * ←4 5 DTR output
5 GND ↔5 4 GND
6 DSR * →6 6 DSR input
7 CTS input ←7 20 RTS output
8 RTS output →8 7 CTS input
9 no connection
TxD = transmit data
RxD = receive data
GND = signal ground
CTS/RTS = handshake
*: Pins 4 and 6 are internally connected. By this, a DTR signal of the PC may be returned as DSR signal to the
PC.

UNIDOSwebline Interfaces
Interface Configuration
D776.131.01/02 5
2.2 Ethernet Interface and UDP
Protocols of the TCP/IP family are used for the
communication between UNIDOSwebline and a PC
via the Ethernet interface, UDP protocols for send-
ing commands via the Ethernet interface. For fur-
ther information about configuring the Ethernet in-
terface please refer to the UNIDOSwebline user man-
ual.
WARNING
The UNIDOSwebline may adversely affect the data
transmission of other clients in the network.
Network Problem!
Via the Ethernet interface, UNIDOSwebline may be
connected to data networks, only if these net-
works do not determine the safety of the patient,
the operator or other persons present, i.e., only
to class A networks as defined in Annex H of
IEC 60601-1: 2005.
Only system administrators, who are capable of
understanding, assessing and controlling the risk
arising from the connection of UNIDOSwebline to
the data network, are authorized to establish the
connection.
It must also be ensured that any future risk re-
sulting from changes to the data network (e.g.
connection of devices affecting the system safety
or changes to the network configuration, etc.) will
be understood, assessed and controlled.
By means of UDP a virtual COM interface is de-
fined. Using an existing terminal program or any
other software for RS232, you can then communi-
cate with UNIDOSwebline via this interface.
•Install a UDP driver on your PC. For information
on the UDP driver recommended by PTW-
Freiburg, refer to the PTW-Freiburg homepage.
•Start the UDP driver.
•Define a virtual COM interface via the UDP
driver.
NOTE
The UDP port number for UNIDOSwebline is 8123.
•Start a terminal program or any other software
for RS232 and select this virtual interface for
communication with UNIDOSwebline.
ÆThe same commands can now be sent to
UNIDOSwebline via Ethernet as via the RS232
interface.

UNIDOSwebline Interfaces
Interface Commands
6 D776.131.01/02
3 Interface Commands
3.1 Principles of Computer
Communication
Between UNIDOSwebline and the connected PC, data
are communicated in the form of ASCII strings,
called commands. All commands are ending with
<CR> (carriage return, hexadecimal 0D) and <LF>
(line feed, hexadecimal 0A). These end marks are
omitted in all command descriptions.
For all communication, a strict ping pong principle
must be observed: after sending a command to the
UNIDOSwebline, the PC must wait for the answer
from UNIDOSwebline before it may send a new
command.
UNIDOSwebline will not send commands on its own; it
only sends answers, e.g. measuring values. If the
PC sends via the interface a command to the
UNIDOSwebline, it will not answer until it has
executed the appropriate actions.
If the PC sends an invalid command, an operator
error or a UNIDOSwebline defect occurs,
UNIDOSwebline will answer with an error message
instead of sending the expected answer.
NOTE
Commands are answered with error messages
while the SETUP menu is displayed or while a
setting is changed via the quickinfo window!
Exception: PTW and SER command
NOTE
To avoid confusion due to user operation at the
UNIDOSwebline keyboard or by VNC, it is recom-
mended to lock the UNIDOSwebline keyboard or
VNC by the KEY;0 command during remote
control of UNIDOSwebline.
NOTE
In the following user manual the character ●is
used to depict a space character contained in a
command.
3.2 Command Structure
Commands are composed of the command key-
word and one or more optional parameters. Key-
word and parameters are separated by semicolons.
If there is no further parameter, a trailing semicolon
is not allowed.
Example:
PTW;UNIDOS2;x.xx;y
↑↑↑↑
│parameter
keyword

UNIDOSwebline Interfaces
Interface Commands
D776.131.01/02 7
3.3 A Sample Session
Perform steps 1 to 4 in the given sequence to set
up UNIDOSwebline and read out measured data.
Step 1: physical setup
Connect the UNIDOSwebline „Serial“ connector to the
RS232 connector of your PC with a suitable cable.
Switch on UNIDOSwebline and set it manually to the
desired measuring parameters. The measurement
screen must be displayed.
Step 2: open communication
Start the communication program on your PC.
Make sure that it is set up correctly.
Send a PTW command. The response must be
UNIDOS2;x.xx where x.xx is the firmware ver-
sion. Repeat this for a maximum of 3 times. If there
is still no correct response, check the setup of the
computer program and the used communication
port.
Step 3: read error status
Send a SE command. The answer has to be
SE;0;0. Otherwise a device error exists and you
have to terminate the communication.
Step 4: start measurement and read data
If step 3 succeeded, send a STA command and
watch the UNIDOSwebline starting a measurement. If
the measured value is displayed, read it by sending
a MV command.
3.4 Command Categories
The commands can be divided into the following
groups:
3.4.1 General Commands
PTW Read device identification and firmware
version
SER Read serial number of the device
KEY Read/Set keyboard lock
BR Read/Set baud rate
HS Read/Set handshake setting
DTD Read/Set date
DTT Read/Set time
3.4.2 Status Request and Diagnosis
S Read measurement status
SE Read error status
SPS Read status of power supply
NEW Recalculate the measured value multiplica-
tors
3.4.3 Measurement and Control Commands
NUL Start zeroing
NUS Read zeroing status
RGE Read / Change measuring range
URE Read/Set radiological or electrical measur-
ing mode
HV Read/Set high voltage
IT Read/Set integration time
STA Start a dose or charge measurement
INT Start an integration measurement
HLD Set the measurement to Hold mode
RES End a dose or charge measurement and
reset the measured values
MV Read measured values
MVM Read upper limit of measuring range
MVR Read display solution

UNIDOSwebline Interfaces
Commands by Functions
8 D776.131.01/02
3.4.4 Data Base Commands for Detectors
DBC Select a detector data record as active
detector
DAV Read/Set the value of a parameter of the
active detector
DBL Load a detector data record from the data
base to the data record work space
DBV Read/Set the value of a parameter of the
data record work space
DBS Save the data record work space in a de-
tector data record of the data base
3.4.5 Data Base Commands for User Settings
DUV Read/Set the value of a parameter of the
user settings
3.4.6 Statistics Commands
SPA Read/Set a statistics parameter
STO Add the displayed measured value to the
statistics
SMC Read the status of the statistics measure-
ment / operate the statistics measurement
SDC Delete an entry/all entries from the statis-
tics list
SDR;x Read an entry of the statistics list
SDR Read the whole contents of the statistics
list
4 Commands by Functions
4.1 Notes on Command
Overview
For each command, the table contains the following
information:
•command and parameter formats
•return format
•permitted parameter range
•default parameter values
are shown in the tables below in bold italics (xx)
•comments
•the keywords of all commands are in CAPITAL
LETTERS and have to be sent in such a way
•wild cards for the parameters are in lower case
letters
•every parameter is separated by a semicolon
•the decimal marker is the point
4.1.1 CRC check sum
The CRC check sum is calculated from all charac-
ters of the command, i.e. from the first character up
to and including the semicolon preceding the CRC
check sum. The polynomial used for calculation is:
1
51216 +++= xxxCRC
The CRC check sum is transmitted in form of a
5-digit ASCII string.
(On request PTW-Freiburg will provide details of the
CRC calculation method.)

UNIDOSwebline Interfaces
Commands by Functions
D776.131.01/02 9
4.2 General Commands
Function
Command
Read device ID and firmware version
PTW
Answer PTW;UNIDOS2;x.xx;y
Parameters UNIDOS2
x.xx
y
device ID
firmware version
optional build number
Timeout ≤0,5 s
Function
Command
Read device serial number
SER
Answer SER;xxxxxx
Parameters xxxxxx device serial number
Timeout ≤0,5 s
Function
Command
Read keyboard lock
KEY
Function
Command
Set keyboard lock
KEY;x
Answer KEY;x
Parameters x0: keyboard locked
1: keyboard unlocked
Timeout ≤0,5 s
Remarks This command also locks operation via VNC client.
Function
Command
Read baud rate
BR
Function
Command
Set baud rate
BR;x
Answer BR;x
Parameter xbaud rate:
1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115000
Timeout ≤0,5 s
Remarks The answer will be sent with the old baud rate. Then the baud rate will be changed.

UNIDOSwebline Interfaces
Commands by Functions
10 D776.131.01/02
Function
Command
Read handshake setting
HS
Function
Command
Set handshake setting
HS;x
Answer HS;x
Parameter x0: handshake switched off
1: handshake switched on
Timeout ≤0,5 s
Remarks The answer will be sent with the old setting. Then the setting will be changed.
Function
Command
Read date
DTD
Function
Command
Set date
DTD;yyyy;mm;dd
Answer DTD;yyyy;mm;dd
Parameter yyyy
mm
dd
year (1990 … 2069)
month (1… 12)
day (1… 31)
Possible
error messages
E;03, E;08
Timeout ≤0,5 s
Function
Command
Read time
DTT
Function
Command
Set time
DTT;hh;mm;ss
Answer DTT;hh;mm;ss
Parameter hh
mm
ss
hours (0… 23)
minutes (0… 59)
seconds (0… 59)
Possible
error messages
E;03, E;08
Timeout ≤0,5 s

UNIDOSwebline Interfaces
Commands by Functions
D776.131.01/02 11
4.3 Status Request and Diagnosis
Function
Command
Read measurement status
S
Answer S;xxx
Parameter xxx RES : Reset
STA : dose/charge measurement in progress
HLD : dose/charge or integration measurement in Hold status
INT : integration measurement in progress
NUL : zeroing in progress
ERR : error status
AUT : autostart mode
WAI : WAIT mode
INI : device will be initialized
Timeout ≤0,5 s
Function
Command
Read error status
SE
Answer SE;x;y
Parameter X
y
error status of the measuring unit
0: no error
1: an error has occurred
error status of the power supply
0: no error
1: an error has occurred
Timeout ≤0,5 s
Function
Command
Read status of power supply
SPS
Answer SPS;a;b;c;d;e;f
Parameter a
b
c
d
e
f
0: no Standby
1: Standby mode
0: mains operation
1: battery operation
battery warning
0: no warning
1: LowBat, rechargeable batteries almost discharged
2: Shutdown threshold reached
status of the battery charging
0: no rechargeable batteries
1: fast charging
2: trickle charge
3: rechargeable batteries completely charged
battery capacity (0… 100) in [%]
battery voltage in [mV]
Timeout ≤0,5 s

UNIDOSwebline Interfaces
Commands by Functions
12 D776.131.01/02
Function
Command
Recalculate the measured value multiplicators
NEW
Answer NEW
Possible
error messages
E;03
Timeout 1 s
Post delay 5 s
Remarks This command initializes a recalculation of all parameters for measuring value determina-
tion (e.g. resolution).
It sets the Trip Output interface contacts to their power-on position.
It is mainly intended to cancel error states.

UNIDOSwebline Interfaces
Commands by Functions
D776.131.01/02 13
4.4 Measurement and Control Commands
Function
Command
Start zeroing
NUL
Answer NUL
Possible
error messages
E;02, E;03, E;11
Timeout 2 s
Remarks Equivalent to pressing the ZERO device control key
The answer is sent immediately. Read the end of zeroing and the result of zeroing by
means of a NUS command.
Function
Command
Read state of zeroing
NUS
Answer NUS;aa;bbbb;cc
Parameters aa
bbbb
cc
0: zeroing successful
1to 15: zeroing not successful
0: zeroing aborted
1to 4095: zeroing is in progress or zeroing finished
remaining time for zeroing (0 … 74)
If a remaining time of 0is transferred, zeroing is finished.
Timeout ≤0,5 s
Remarks If the zeroing was successful the answer has to be NUS;0;bbbb;0.
Function
Command
Read measuring range
RGE
Function
Command
Change measuring range
RGE;x
Answer RGE;x
Parameters x0: Low
1: Medium
2: High
Possible
error messages
E;03
Timeout 3 s

UNIDOSwebline Interfaces
Commands by Functions
14 D776.131.01/02
Function
Command
Read measuring mode (radiological or electrical)
URE
Function
Command
Set radiological or electrical measuring mode
URE;x
Answer URE;x
Parameters x0: electrical
1: radiological
Possible
error messages
E;03
Timeout 2 s
Function
Command
Read high voltage
HV
Function
Command
Set high voltage
HV;xxxx
Answer HV;xxxx
Parameters xxxx high voltage in volts (-400 …+400); in the case of positive values the
+ sign needs not to be entered
Possible
error messages
E;03, E;08
Timeout 15 s
Remarks The answer is sent immediately before the high voltage is adjusted to the desired value.
Function
Command
Read integration time for integration measurement
IT
Function
Command
Set integration time for integration measurement
IT;xxxx
Answer IT;xxxx
Parameters xxxx integration time in seconds (1 … 60 … 9999)
Possible
error messages
E;03
Timeout 3 s
Function
Command
Start a dose or charge measurement
STA
Answer STA
Possible
error messages
E;02, E;03
Timeout 2 s
Remarks Equivalent to pressing the MEAS device control key

UNIDOSwebline Interfaces
Commands by Functions
D776.131.01/02 15
Function
Command
Start an integration measurement
INT
Answer INT
Possible
error messages
E;02, E;03
Timeout 2 s
Remarks Equivalent to pressing the INTEG device control key
Function
Command
Set the measurement to Hold-mode
HLD
Answer HLD
Possible
error messages
E;02, E;03
Timeout 2 s
Remarks Equivalent to pressing the HOLD device control key
Function
Command
End a dose or charge measurement and reset the measured values
RES
Answer RES
Possible
error messages
E;02, E;03
Timeout 2 s
Remarks Equivalent to pressing the RESET device control key

UNIDOSwebline Interfaces
Commands by Functions
16 D776.131.01/02
Function
Command
Read measured values
MV
Answer MV;a;bb;cc.c;±d.dddE±ee;f;g;±h.hhhE±ii;k;±llllE±mm;nnnnn
Parameters a
bb
cc.c
±d.dddE±ee
±h.hhhE±ii
±llllE±mm
f
g
k
nnnnn
measuring status:
0: reset
1: dose or charge measurement in progress
2: dose or charge measurement in Hold mode
3: integration measurement in progress
4: integration measurement in Hold mode (integration time elapsed)
5: zeroing in progress
6: error status
7: autostart mode
8: WAIT mode
is a two-digit decimal number. This is what the individual bits signify, if set
(error flag):
Bit .0 = dose rate or current is in OVERLOAD
Bit .1 = dose or charge has been in OVERLOAD since start of
measurement or is still in OVERLOAD
Bit .2 = HV ERROR occurs at dose rate or current measurement
Bit .3 = during dose or charge measurement a HV ERROR has occurred
or is still existent
Bit .0 is the least significant bit.
measuring time in seconds with one to seven digits before the decimal
point and one digit after the decimal point
measured value of dose or charge
measured value of dose rate or current
mean value of dose rate or current since start of measurement
Measured values are shown in scientific notation. The mantissa field con-
sists always of six characters. The numbers of digits of the mantissa vary
depending on the measured value; spaces will be inserted to the left, if
necessary. If the mantissa is positive a space is transferred instead of the
+ sign. The exponent is always sent as two digit number with leading
zeros, if necessary. The algebraic sign of the exponent is always trans-
ferred.
0: resolution ≥0,5 %, measured value of dose or charge is not marked
with message LOW SIGNAL
1: resolution ≤0,5 %, measured value of dose or charge is marked with
message LOW SIGNAL
0: measured value of dose or charge is not marked with message LOW
AUTO SIG
1: measured value of dose or charge is marked with message LOW
AUTO SIG
0: resolution ≥0,5 %, measured value of dose rate or current is not
marked with message LOW SIGNAL
1: resolution ≤0,5 %, measured value of dose rate or current is marked
with message LOW SIGNAL
CRC check sum (refer to section 4.1.1)
Timeout ≤0,5 s

UNIDOSwebline Interfaces
Commands by Functions
D776.131.01/02 17
Function
Command
Read upper limit of measuring range
MVM or MVM;a
Answer MVM;a;b.bbbE±cc
Parameters a
b.bbbE±cc
0: Low
1: Medium
2: High
If the measuring range is not prompted in command, upper limit of the
adjusted measuring range in transferred in answer.
upper limit of measuring range
The upper limit of measuring range is formatted in scientific notation.
Timeout ≤0,5 s
Function
Command
Read display resolution
MVR or MVR;a
Answer MVR;a;±b.bbbE±cc;±d.dddE±ee
Parameters a
±b.bbbE±cc
±d.dddE±ee
0: Low
1: Medium
2: High
If the measuring range is not prompted in command, the display resolu-
tion of the adjusted measuring range in transferred in answer.
display resolution of dose or charge, for further details see measuring
value at MV command.
display resolution of dose rate or current, for further details see measur-
ing value at MV command.
Timeout ≤0,5 s

UNIDOSwebline Interfaces
Commands by Functions
18 D776.131.01/02
4.5 Data Base Commands for Detectors
NOTE
All parameters of a detector are condensed in a
list. To access a parameter a number is used.
List of parameters see section 4.5.1.
NOTE
Changing parameters can either be done in the
data record of the active detector or in a so-
called data record work space.
The active detector is selected with the DBC
command.
With the DBL command a data record is loaded
to the data record work space. Changes on the
data record work space have to be saved in the
data base with the DBS command.
NOTE
Detector data records can only be deleted di-
rectly at the device but not via an interface.
Function
Command
Select a detector data record as active detector
DBC;x;y
Answer DBC;x;y
Parameter x
y
number of the detector data record
0: abort, if the new high voltage is higher than the actually set high
voltage
1: skip the warning, that the new high voltage is higher than the actually
set high voltage
Possible
error messages
E;08, E;19, E;21, E;22, E;23, E;25
Timeout ≤0,5 s
Remarks The data record will be loaded and the new values will be set.
The UNIDOSwebline is in WAIT mode until the new high voltage is adjusted. During this time
the Scommand will be answered with S;WAI.

UNIDOSwebline Interfaces
Commands by Functions
D776.131.01/02 19
Function
Command
Read the value of a parameter of the active detector
DAV;p
Function
Command
Set the value of a parameter of the active detector
DAV;p;y
Answer DAV;p;y;zzzzz
Parameter p
y
zzzzz
index of the parameter, refer to list in section 4.5.1
value of the parameter
CRC check sum (refer to section 4.1.1)
Timeout ≤0,5 s
Remarks The value of a text parameter can be removed by sending an empty parameter (i.e.
DAV;p;).
Function
Command
Load a detector data record from the data base to the data record work space
DBL;x
Answer DBL;x
Parameter xnumber of the detector data record
Possible
error messages
E;08, E;19, E;21
Timeout ≤0,5 s
Function
Command
Read the value of a parameter of the data record work space
DBV;p
Function
Command
Set the value of a parameter of the data record work space
DBV;p;y
Answer DBV;p;y;zzzzz
Parameter p
y
zzzzz
index of the parameter, refer to list in section 4.5.1
value of the parameter
CRC check sum (refer to section 4.1.1)
Possible
error messages
E;07, E;08, E;19
Timeout ≤0,5 s
Remarks The value of a text parameter can be removed by sending an empty parameter (i.e.
DBV;p;).
Function
Command
Save the data record work space in a detector data record of the data base
DBS;x
Answer DBS;x
Parameter xnumber of the detector data record
Possible
error messages
E;08, E;19, E;24
Timeout ≤0,5 s

UNIDOSwebline Interfaces
Commands by Functions
20 D776.131.01/02
4.5.1 List of Parameters for the Detector Data records
Index Name of the
parameter Description of the parameter Type of the parameter Possible values
0 Record No number of data record
read only
integer value 0… 51
1 Identifier identifier of the detector,
e.g. "Farmer Chamber"
text 31 characters max.
2 S/N serial number of the detec-
tor; e.g. "00012"
text 11 characters max.
3 Type number type number of the detec-
tor; e.g. "T10021"
text 15 characters max.
4 Detector type detector type selection 0: vented ion chamber
1: sealed ionization chamber
2: liquid ion chamber
3: semiconductor detector
4: diamond detector
5 Quantity measuring quantity selection 0: Absorbed dose to water DW
1: Air kerma KA
2: Exposure JS
3: Photon equivalent dose Hx
4: Ambient equivalent dose H*(10)
5: Activity A
6: Air kerma strength KA
7: Dose length product DLP
8: Dose area product DAP
6 Unit radiological unit selection 0: Gy
1: R
2: Sv
3: Bq
4: Ci
5: Gy·m
6: R·m
7: Gy·m²
8: R·m²
7 Time display time unit for dose rate indi-
cation
selection 0: 1/s,
1: 1/min
2: 1/h
8 Safe Calibration Safe Calibration
read only
selection 0: not officially calibrated
1: officially calibrated
9 CalQuality radiation quality to which
the calibration factor refers
text 20 characters max.
10 Calibration factor calibration factor decimal value 1.0 … < 1.000E13
11 CalTemperature calibration temperature selection 0: 20°C
1: 22°C
12 CalDate calibration date date yyyy-mm-dd hh:mm:ss
time setting optionally
13 Next calibration date for next calibration date yyyy-mm-dd hh:mm:ss
time setting optionally