GitHub

Petoi Bittle commands

To interact with the robot, the library exposes a PetoiBittle.Command interface and the PetoiBittle.send_command function.

PetoiBittle.before_command — Function
before_command(connection::Connection, command::Command)

A callback that is being called right before sending the command over the connection. A more specific Command can add custom logic that needs to be executed right before sending the command. By default does nothing.

See also: after_command

source
PetoiBittle.after_command — Function
after_command(connection::Connection, command::Command)

A callback that is being called right after sending the command over the connection but before reading the output. A more specific Command can add custom logic that needs to be executed right after sending the command. By default does nothing.

See also: before_command

source
PetoiBittle.command_return_type — Function
command_return_type(::Type{<:Command})

Different commands may have different response (return) types while some commands don't imply any response.

If a command has a specific response type, it should implement

PetoiBittle.command_return_type(::Type{<:MySpecificCommand}) = MySpecificCommandResponse

as well as 

function PetoiBittle.deserialize_from_bytes(bytes, ::Type{MySpecificCommandResponse}, startidx, endidx)
    # ...
    return MySpecificCommandResponse(...)
end

to deserialize the response from raw bytes. The bytes will contain everything that has been captured after the command has been sent until the symbol.

In this case, a command should also implement

function PetoiBittle.validate_return_type(bytes, ::Type{MySpecificCommandResponse}, startidx, endidx)
    return true # false
end

to validate the content in bytes. The PetoiBittle.validate_return_type will be called before PetoiBittle.deserialize_from_bytes. If the validate function returns false, the PetoiBittle.send_command discards the content in bytes and read the output again.

Default return type is assumed to be [PetoiBittle.NoResponse], which is a convention that the command does not have any response. In this case the return value of the PetoiBittle.send_command is nothing and the deserialization procedure is not being called. That also means everything the Petoi Bittle sends after the command has been executed is being ignored.

See also: PetoiBittle.deserialize_from_bytes

source

The list of available commands

The full list of available commands for Petoi Robots and their specification can also be found on the Petoi Bittle website in the Serial Protocol section. This library implements a subset of commands. PRs are welcome to add new commands!

To get the list of all available commands implemented in the package use in REPL:

julia> subtypes(PetoiBittle.Command)6-element Vector{Any}:
 PetoiBittle.GyroCalibrate
 PetoiBittle.GyroCalibrateSave
 PetoiBittle.GyroStats
 PetoiBittle.MoveJoints
 PetoiBittle.Rest
 PetoiBittle.Skill
Note

This command only works in Julia REPL.

PetoiBittle.Rest — Type
Rest()

A command without arguments. Sends a command to get into resting position.

source
PetoiBittle.Skill — Type
Skill(skill_name)

A command that executes a predefined skill_name. Please consult the Petoi documentation to get the list of predefined skills (e.g. here). You can also add your own skills and attach names to them.

skill_name should be an iterable of Char, e.g. String or a Vector{Char}.

source
PetoiBittle.MoveJoints — Type
MoveJoints(joint_movements_as_named_tuple...)
MoveJoints(single_tuple_of_move_joint_specs)

A PetoiBittle.Command that specifies which joint to move at which angle. Can be constructed from a vararg argument list of named tuples with id and angle keys present or a single tuple containing multiple PetoiBittle.MoveJointSpec.

julia> PetoiBittle.MoveJoints(
           (id = 8, angle = 10),
           (id = 9, angle = 20)
       )
PetoiBittle.MoveJoints{2}((PetoiBittle.MoveJointSpec(8, 10), PetoiBittle.MoveJointSpec(9, 20)))

julia> PetoiBittle.MoveJoints(
           (id = 9, angle = 10),
           (id = 9, angle = 20)
       )
ERROR: Cannot create MoveJoints. Duplicate `id` found `9`. Set `check_unique = false` to skip the check.
[...]

See also: PetoiBittle.MoveJointSpec

source
PetoiBittle.MoveJointSpec — Type
MoveJointSpec(id::Int, angle::Int)

A command specification for a joint with id id to change its angle to angle. Note, that this structure is not a command by itself. To move a single joint you should still use the PetoiBittle.MoveJoints command.

julia> convert(PetoiBittle.MoveJointSpec, (id = 1, angle = 10))
PetoiBittle.MoveJointSpec(1, 10)

julia> convert(PetoiBittle.MoveJointSpec, (id = 1, ))
ERROR: Cannot convert NamedTuple (id = 1,) to `MoveJointSpec(id = ..., angle = ...)`. Missing key `angle`.
[...]

See also: PetoiBittle.MoveJoints

source
PetoiBittle.GyroCalibrate — Type
GyroCalibrate(; wait_before::Float64 = 2.0, wait_after::Float64 = 15.0, verbose = true)

Sends a command to re-calibrate the gyro. The wait_before and wait_after arguments are in seconds. The verbose setting controls whether to print informational messages or not.

Note: This command should be executed from a "resting" state. An example of a resting state might be calibration posture or rest posture. Either use the PetoiBittle.Skill command or PetoiBittle.Rest before calibrating the gyro.

It is advised to wait a little bit before starting the calibration process (especially after executing a PetoiBittle.Skill). By default waits for 2 seconds. The entire process also takes some time, but it is possible to configure it. By default calibrates for 15 seconds. Uses sleep under the hood.

source