.. _uss5-commands: Commands ======== You can find the command set at :ref:`uss5-command-set`. .. note:: Byte 0 in this documentation refers to the first data byte after the header. Individual bytes are transferred with the Least Significant Bit first. In the following, the CAN IDs are given as an offset to the base address, so ``+3`` means base address plus 3. CMD_CONNECT ----------- Use this command to establish and check the connection to the board. Command ID: ``+0`` =============== = = = = = = = ``CMD_CONNECT`` 0 0 0 0 0 0 0 =============== = = = = = = = Answer ID: ``+1`` =============== = = = = = = = ``CMD_CONNECT`` 1 2 3 4 5 6 7 =============== = = = = = = = CMD_SET_CHANNEL_ACTIVE ---------------------- This command can be used to activate or deactivate individual sensors without transmitting the complete parameter set. Two bytes for the channels 1 to 8 and 9 to 16 contain the information whether the sensors should be active. These bytes are bit-coded, each bit representing the state of one sensor. Every active channel is marked with a 1. For example, ``0x1F`` as the first byte means channels 1 to 5 are active and channels 6 to 8 are not active. Command ID: ``+0`` ========================== ================ ================= = = = = = ``CMD_SET_CHANNEL_ACTIVE`` (Sensors 1 to 8) (Sensors 9 to 16) 0 0 0 0 0 ========================== ================ ================= = = = = = Answer No answer. CMD_GET_DATA_1TO8 ----------------- This command is used to request the readings of sensors 1 to 8. Command ID: ``+0`` ===================== = = = = = = = ``CMD_GET_DATA_1TO8`` 0 0 0 0 0 0 0 ===================== = = = = = = = Answer (two parts) IDs: ``+2``, ``+3`` ===================== = ====================================== = ========== ``CMD_GET_DATA_1TO8`` 0 Values for sensors 1-4 (one byte each) 0 (reserved) ``CMD_GET_DATA_1TO8`` 1 Values for sensors 5-8 (one byte each) 0 (reserved) ===================== = ====================================== = ========== The measurement values are given according to the configured sensor group resolution (see :ref:`uss5-parameters`). .. note:: This is a legacy command. The maximum value is 255 (1 Byte). Higher bits are not transmitted. CMD_GET_DATA_9TO16 ------------------ This command is used to request the readings of sensors 9 to 16. Command ID: ``+0`` ====================== = = = = = = = ``CMD_GET_DATA_9TO16`` 0 0 0 0 0 0 0 ====================== = = = = = = = Answer (two parts) IDs: ``+4``, ``+5`` ====================== = ======================================== = ========== ``CMD_GET_DATA_9TO16`` 0 Values for sensors 9-12 (one byte each) 0 (reserved) ``CMD_GET_DATA_9TO16`` 1 Values for sensors 13-16 (one byte each) 0 (reserved) ====================== = ======================================== = ========== The measurement values are given according to the configured sensor group resolution (see :ref:`uss5-parameters`). .. note:: This is a legacy command. The maximum value is 255 (1 Byte). Higher bits are not transmitted. .. _uss5-cmd_write_paraset: CMD_WRITE_PARASET ----------------- Use this command to transfer a complete parameter set to the USBoard-USS5. The parameters are stored volatile, which means that they will be lost when the board is switched off. To conveniently configure the board, use the graphical parameter editor. After transmitting the parameter set, it will immediately be used by the board. Command ID: ``+0`` The command consists of nine messages sent one after the other, each containing some bytes of the parameter set. ===================== = ============== ``CMD_WRITE_PARASET`` 0 Bytes 1 to 6 ``CMD_WRITE_PARASET`` 1 Bytes 7 to 12 ``CMD_WRITE_PARASET`` 2 Bytes 13 to 18 ``CMD_WRITE_PARASET`` 3 Bytes 19 to 24 ``CMD_WRITE_PARASET`` 4 Bytes 25 to 30 ``CMD_WRITE_PARASET`` 5 Bytes 31 to 36 ``CMD_WRITE_PARASET`` 6 Bytes 37 to 42 ``CMD_WRITE_PARASET`` 7 Bytes 43 to 48 ``CMD_WRITE_PARASET`` 8 Bytes 49 to 54 ===================== = ============== Answer ID: ``+8`` Each message is answered individually. The first 8 answers are identical ===================== = = = = = = = ``CMD_WRITE_PARASET`` 0 0 0 0 0 0 0 ===================== = = = = = = = and the last answer contains the sum of the first 48 bytes in the parameter set. ===================== ======== ========= = = = = = ``CMD_WRITE_PARASET`` low byte high byte 0 0 0 0 0 ===================== ======== ========= = = = = = CMD_WRITE_PARASET_TO_EEPROM --------------------------- Use this command to write a complete parameter set into the board's EEPROM. The parameters are stored non-volatile, which means that they will be used again the next time the USBoard-USS5 is switched on. To comfortably configure the board, use the graphical parameter editor. The parameter set will immediately be used after transmission. Command ID: ``+0`` The command works identically to :ref:`uss5-cmd_write_paraset`, the only difference is the use of the command byte ``CMD_WRITE_PARASET_TO_EEPROM``. Answer ID: ``+9`` The answer is identical to the answers to :ref:`uss5-cmd_write_paraset`, the only difference is the use of the command byte ``CMD_WRITE_PARASET_TO_EEPROM``. CMD_READ_PARASET ---------------- Use this command to read a complete parameter set from the USBoard-USS5. Command ID: ``+0`` ==================== = = = = = = = ``CMD_READ_PARASET`` 0 0 0 0 0 0 0 ==================== = = = = = = = Answer ID: ``+6`` The answer consists of nine messages sent one after the other, each containing some bytes of the parameter set. ==================== = ============== ``CMD_READ_PARASET`` 0 Bytes 1 to 6 ``CMD_READ_PARASET`` 1 Bytes 7 to 12 ``CMD_READ_PARASET`` 2 Bytes 13 to 18 ``CMD_READ_PARASET`` 3 Bytes 19 to 24 ``CMD_READ_PARASET`` 4 Bytes 25 to 30 ``CMD_READ_PARASET`` 5 Bytes 31 to 36 ``CMD_READ_PARASET`` 6 Bytes 37 to 42 ``CMD_READ_PARASET`` 7 Bytes 43 to 48 ``CMD_READ_PARASET`` 8 Bytes 49 to 54 ==================== = ============== CMD_GET_ANALOGIN ---------------- Use this command to acquire the data of the four analog inputs. Command ID: ``+0`` ==================== = = = = = = = ``CMD_GET_ANALOGIN`` 0 0 0 0 0 0 0 ==================== = = = = = = = Answer ID: ``+7`` Because the resolution of the on-board AD-converter is 12 bit, the first part of the answer is made up of the four low bytes. Bytes 5 and 6 contain the upper 4 bits of the four channels. ==================== =================== =================== =================== =================== ============================== ============================== = ``CMD_GET_ANALOGIN`` low 8 bit channel 0 low 8 bit channel 1 low 8 bit channel 2 low 8 bit channel 3 high 4 bits of channel 0 and 1 high 4 bits of channel 3 and 4 0 ==================== =================== =================== =================== =================== ============================== ============================== = CMD_GET_DATA ------------ This command is used to request the readings of selected sensors. The selection is done by a bit mask where bit 0 stands for group 0, bit 1 stands for group 1 and so on. There will be one answer message per selected group. Command ID: ``+0`` ================= ================= = = = = = = ``CMD_GET_DATA`` (selected groups) 0 0 0 0 0 0 ================= ================= = = = = = = Answer ID: ``+(13 + group_id)`` ================ ====== ==================== ==================== ==================== ==================== ============================== ============================== ``CMD_GET_DATA`` (info) lower 8 bit sensor 0 lower 8 bit sensor 1 lower 8 bit sensor 2 lower 8 bit sensor 3 high 4 bits of sensors 0 and 1 high 4 bits of sensors 3 and 4 ================ ====== ==================== ==================== ==================== ==================== ============================== ============================== The `info` byte contains * 2 bits encoding the group id (0 to 3) * 2 bits encoding the sensor resolution (0 for 1 cm, 1 for 0.5 cm, 2 for 0.25 cm, 3 for 0.125 cm) * 4 bits denoting the sending sensor, either ``0xFF`` if all sensors are sending or the bit of the active sensor set to 1 for cross echo mode The `lower 8 bit` byte of a sensor can also contain an error code: * 0 indicates that the sensor is not physically connected to the USBoard-USS5. * 1 indicates that an object is closer than the minimum range of the sensor. * 2 indicates that the sensor is active and sending pulses but has not received any echo. It usually occurs when the object is too far.