diff --git a/ur_msgs/srv/SetIO.srv b/ur_msgs/srv/SetIO.srv
index ddc2b44cb5575598e43a071da923afe9045b458a..0bea454e4f305035ed3bdf522e53a55dc96d6cc3 100644
--- a/ur_msgs/srv/SetIO.srv
+++ b/ur_msgs/srv/SetIO.srv
@@ -1,7 +1,40 @@
+# Service allows setting digital (DIO) and analog (AIO) IO, as well as flags
+# and configuring tool voltage.
+#
+# This service has three request fields (see below).
+#
+# When setting DIO or AIO pins to new values:
+#
+#  fun    The function to perform
+#  pin    Numeric ID of the pin to set
+#  state  Desired pin state (signal level for analog or STATE_(ON|OFF) for DIO and flags)
+#
+# When configuring tool voltage:
+#
+#  fun    Set to FUN_SET_TOOL_VOLTAGE
+#  pin    Ignored
+#  state  Desired tool voltage (use STATE_TOOL_VOLTAGE constants)
+
+# constants
+
+# valid function values
+#
+# Note: 'fun' is short for 'function' (ie: the function the service should perform).
 int8 FUN_SET_DIGITAL_OUT = 1
 int8 FUN_SET_FLAG = 2
 int8 FUN_SET_ANALOG_OUT = 3
 int8 FUN_SET_TOOL_VOLTAGE = 4
+
+# valid values for 'state' when setting digital IO or flags
+int8 STATE_OFF = 0
+int8 STATE_ON = 1
+
+# valid 'state' values when setting tool voltage
+int8 STATE_TOOL_VOLTAGE_0V = 0
+int8 STATE_TOOL_VOLTAGE_12V = 12
+int8 STATE_TOOL_VOLTAGE_24V = 24
+
+# request fields
 int8 fun
 int8 pin
 float32 state