Sunday, October 4, 2015

Servo Controller: Interface Control Document (ICD)

As I add new capabilities to the servo controller, I want to document the commands into a single Interface Control Document (ICD). I'll continue to edit this post as the project progresses to capture all the servo controller commands and responses.


Structures


' Must set Sequential with Pack = 1 so .NET creates a byte array
' with the Byte as 1 byte (and not as 2).
<StructLayout(LayoutKind.Sequential, Pack:=1)> _
Public Structure CommandSetServoValueStructure
    Public command As Byte
    Public servoNumber As UInt16
    Public newValue As UInt16

    Public Function getBytes() As Byte()
        Dim binaryBytes(5) As Byte
        Dim pointerCommand As IntPtr = Marshal.AllocHGlobal(Marshal.SizeOf(Me))
        Marshal.StructureToPtr(Me, pointerCommand, False)
        Marshal.Copy(pointerCommand, binaryBytes, 0, Marshal.SizeOf(Me))
        Marshal.FreeHGlobal(pointerCommand)
        Return binaryBytes
    End Function
End Structure

struct CommandSetServoValueStructure
{
  byte     command;
  uint16_t servoNumber;
  uint16_t newValue;
  // Must denote structure as packed for variables to be
  // properly interpreted from a byte array.
} __attribute__((__packed__));


Sending Binary Commands (.NET)


Dim thisCommand As CommandSetServoValueStructure
' Fill in thisCommand as appropriate.
Dim binaryBytes() As Byte = thisCommand.getBytes
connectedSerialPort.Write(binaryBytes, 0, 5)

where 5 is the size of the structure


Binary Commands


To enter binary mode, send a value of 128 after the controller starts up.

Clear Command

Send an array of at least five 0s to force the microcontroller to fulfill any existing inputs and be ready for new input. Sending additional 0s will keep the controller in a cleared state.
Outgoing Data:
0
Response Data:
<none>

Set Servo Position in Percent

Call to set a servo's position in percent.
Outgoing Data:
CommandSetServoValueStructure
CommandSetServoValueStructure.command = 1
CommandSetServoValueStructure.servoNumber = <Index of Servo to Change>
CommandSetServoValueStructure.newValue = <0 to 100>
Response Data:
<none>

Set Servo Upper Limit in Pulses

Call to set a servo's upper limit in pulses. If sending too high then that can permanently damage the servo.
Outgoing Data:
CommandSetServoValueStructure
CommandSetServoValueStructure.command = 2
CommandSetServoValueStructure.servoNumber = <Index of Servo to Change>
CommandSetServoValueStructure.newValue = <0 to 4096>
Response Data:
<none>

Set Servo Lower Limit in Pulses

Call to set a servo's lower limit in pulses. If sending too low then that can permanently damage the servo.
Outgoing Data:
CommandSetServoValueStructure
CommandSetServoValueStructure.command = 3
CommandSetServoValueStructure.servoNumber = <Index of Servo to Change>
CommandSetServoValueStructure.newValue = <0 to 4096>
Response Data:
<none>


ASCII Commands


To enter ASCII mode, send a value of 10 (new line) after the controller starts up.

Set Servo

Select which servo to control.
Outgoing Data:
s=<Index of Servo to Change>
Response Data:
Debug Servo:<Index of Servo to Change>

Set Servo Position in Percent

Call to set a servo's position in percent. Must use "Set Servo" command first to specify which servo to control.
Outgoing Data:
p=<Percent Value to Set>
Response Data:
Set Percent:<Percent Value to Set>

Set Servo Position in Pulses

Call to set a servo's position in pulses. Must use "Set Servo" command first to specify which servo to control.
Outgoing Data:
v=<Pulse Value to Set>
Response Data:
Set pulse:<Pulse Value to Set>

Set Upper Limit in Pulses

Call to set a servo's upper limit in pulses. If sending too high then that can permanently damage the servo. Must use "Set Servo" command first to specify which servo to control.
Outgoing Data:
u=<Pulse Value to Set>
Response Data:
Set upper pulse:<Pulse Value to Set>

Set Lower Limit in Pulses

Call to set a servo's lower limit in pulses. If sending too low then that can permanently damage the servo. Must use "Set Servo" command first to specify which servo to control.
Outgoing Data:
l=<Pulse Value to Set>
Response Data:
Set lower pulse:<Pulse Value to Set>



Copyright (c) 2015 Clinton Kam
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

No comments:

Post a Comment