usm-pan

USM Sonar Rotator Development and Integration

USM API v3.2

The USM API provides methods for communicating with a sonar head rotational actuator and/or vertical lift assembly using single or dual lift motors. All motors (rotational or lift) are controlled using UDP datagrams. The datagrams are ASCII comma-delimited messages. Further, the UDP ports are broadcast over 255.255.255.255, allowing the PLC to be configured with static or DHCP IPv4 addressing.

The default networking:

• IPv4 address: 192.168.0.250
  • Send/Recv on the same port, respectively
• Rotational Actuator port: 51000
• Lift Motor port: 52000
  • if a second lift motor is present, it is automatically sync’d to mirror the primary lift motor as determined by the hardware profile below

Available firmware configurations support the following hardware profiles:

• rotator only,
• single-lift + rotator,
• dual-lift + rotator,
• single-lift only,
• dual-lift only

It is important to note that all motors are 19-bit absolute-encoded, dual-encoded motors. They always know where they are and can report the following error and resting position of any movement with high-precision (<0.001 degree).

ToDo: Implement a conversion such that the lift motors convert between angular and linear units (as determined by gear ratio)

Coming soon: Pulse Per Second (PPS) integration

Status Message

When reporting status messages, the PLC sends a UDP datagram to a PC at up to 50 times per second. The message contains the status, position, encoder count, speed, following error, and timestamp for the rotational actuator.

$<header>,<status>,<position>,<encoder>,<speed>,<following_error><timestamp>*<checksum>

$USM_STAT,2,-30.0000,270015,10.0000,0.0150,2025-05-28T16:51:34.231Z*17

<header> STRING

• “USM_STAT”

<status> INTEGER

Value	Description
0	idle
1	programs loading
2	programs running
3	programs unloading
4	reserved
5	reserved
6	reserved
7	reserved

<position> FLOAT

• value indicating motor(s) position at timestamp

<speed> FLOAT

• s = speed (deg/sec)

<following_error> FLOAT

• f = following error, the difference between the expected and actual position
  • slower speeds equate to smaller following error

<timestamp> STRING

• UTC timestamp in OSI 8601 format
  • YYYY-MM-DDThh:mm:ss.ffffff

<checksum> STRING

• NMEA-style, XOR checksum of all characters between $ and * but not including them

Command Message

PC sends UDP datagrams to PLC asynchronously. The messages contain a command and its operands.

$<header>,<command>,<mode>,<position_a>,<position_b><offset><speed>*<checksum>

$USM_CMD,6,1,-20.0,20.0,5,10*40

<header> STRING

• “USM_CMD”

<command> INTEGER

Value	Action	Description
0	profile	set the hardware profile
1	halt	stop the current motor action
2	home	return to origin
3	calibrate	if port=51000 then set current position as new home (rotator) if port=52000 then find min/max range using limit switches (lift)
4	vector to	goto <positon_a> at <speed>
5	deploy	if port=51000 (reserved) if port=52000 then goto maximum position
6	sweep zone	goto <positon_a> at <speed>, then goto <positon_b> at same speed, opposite direction

<mode> INTEGER

• IF <command>=0: m = hardware profile
  • 0=rotator only,
  • 1=single-lift + rotator,
  • 2=dual-lift + rotator,
  • 3=single-lift only,
  • 4=dual-lift only
• IF <command>!=0: m = mode [0 - 50], [message output frequency (Hz)]

<position_a> FLOAT

• position of first sweep boundary or position vector

<position_b> FLOAT

• position of second sweep boundary

<offset> FLOAT

• r = rotational offset
  • setting this to non zero is useful for
    • setting in all commands to use as a global offset (new origin)
    • setting in a single command (i.e. sweep between two angles relative to this offset)

<speed> FLOAT

• s = speed (deg/sec)

<checksum> STRING

• XOR checksum of all characters between $ and * but not including them
  • Not yet required - just send *00