Build HAT Serial Protocol
Colophon
© 2020 Raspberry Pi (Trading) Ltd.
This documentation is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND).
build-date: 2021-10-15
build-version: githash: 61115e7-dirty
Legal Disclaimer Notice
TECHNICAL AND RELIABILITY DATA FOR RASPBERRY PI PRODUCTS (INCLUDING DATASHEETS) AS MODIFIED FROM
TIME TO TIME (“RESOURCES”) ARE PROVIDED BY RASPBERRY PI (TRADING) LTD (“RPTL) "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE
LAW IN NO EVENT SHALL RPTL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THE RESOURCES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
RPTL reserves the right to make any enhancements, improvements, corrections or any other modifications to the
RESOURCES or any products described in them at any time and without further notice.
The RESOURCES are intended for skilled users with suitable levels of design knowledge. Users are solely responsible for
their selection and use of the RESOURCES and any application of the products described in them. User agrees to
indemnify and hold RPTL harmless against all liabilities, costs, damages or other losses arising out of their use of the
RESOURCES.
RPTL grants users permission to use the RESOURCES solely in conjunction with the Raspberry Pi products. All other use
of the RESOURCES is prohibited. No licence is granted to any other RPTL or other third party intellectual property right.
HIGH RISK ACTIVITIES. Raspberry Pi products are not designed, manufactured or intended for use in hazardous
environments requiring fail safe performance, such as in the operation of nuclear facilities, aircraft navigation or
communication systems, air traffic control, weapons systems or safety-critical applications (including life support
systems and other medical devices), in which the failure of the products could lead directly to death, personal injury or
severe physical or environmental damage (“High Risk Activities”). RPTL specifically disclaims any express or implied
warranty of fitness for High Risk Activities and accepts no liability for use or inclusions of Raspberry Pi products in High
Risk Activities.
Raspberry Pi products are provided subject to RPTL’s Standard Terms. RPTL’s provision of the RESOURCES does not
expand or otherwise modify RPTL’s Standard Terms including but not limited to the disclaimers and warranties expressed
in them.
Legal Disclaimer Notice 1
Build HAT Serial Protocol
Introduction
The BuildHAT is a board that provides an interface between a Raspberry Pi host and up to four LEGO LPF2 (LEGO Power
Functions version 2) devices. Supported LPF2 devices include a wide range of actuators and sensors. Firmware running
on the HAT deals with the hard real-time requirements of the LPF2 devices, including monitoring for connection and
disconnection events and interrogating devices to determine their capabilities and properties.
The HAT communicates with the Raspberry Pi host over the 'command port', a 115200 baud serial interface with eight
bits per character, no parity and one stop bit ('8N1'). There is no flow control. The command port protocol is entirely in
plain text, and it is perfectly possible to simply run a terminal emulator on the host and interact manually with the HAT.
When experimenting the HAT in this way it is convenient to enable echo mode so that you can see what you are typing:
see the description of the echo command below. See also the plimit command, which must be sent before many
operations will work correctly.
This document describes the commands available over that interface.
NOTE
A Python library is provided that provides a higher-level interface to the functions of the HAT: in most cases it will be
preferable to use that library rather than the lower-level commands described here.
Introduction 2
Build HAT Serial Protocol
Port and Device Basics
The firmware numbers the ports from 0 to 3. There is the notion of the 'current port', set using the port command. Many
commands implicitly address the current port.
Each port may have a device connected to it. A device may be 'active', which means that it communicates with the HAT
using a serial interface, or it may be 'passive'. Passive devices include some lights and motors, although most types of
motor are active devices. Active devices can offer some feedback to the HAT: for example, an active motor might contain
position or speed sensors to allow it to be controlled precisely.
An active device has up to sixteen 'modes'. A mode can be thought of as a small memory buffer in the device, much like
the concept of a 'characteristic' in Bluetooth terminology. Some modes are intended to be written to, to control the device;
some are intended to be read from, to extract sensor readings for example.
When a device is plugged in to the HAT, the HAT emits a 'connected' message followed by the information it has about
the device. For a passive device this will just be an identifying code number. For an active device this will be an identifying
code number followed by other information including the connection baud rate, software and hardware version numbers
and a list of the available modes. See the list command below for more detail.
When a device is unplugged from the HAT, a 'disconnected' message is emitted.
Port and Device Basics 3
Build HAT Serial Protocol
Device Power
The LPF2 connector supplies power to a connected device in two ways. The first of these is a normal digital logic power
supply at +3.3V which is always present. If a device attempts to draw too much current from this supply then a 'Port
power fault' message is emitted for as long as the fault persists.
The second power source is at about +7.2V and intended for driving motors and other relatively high-power devices. This
is supplied by a separate dedicated driver IC for each port. If a fault is detected on this supply then a 'Motor power fault'
message is emitted repeatedly. This fault condition is latched in hardware and must be cleared explicitly after the cause
of the fault has been resolved: see the clear_faults command below.
The motor driver ICs can output PWM waveforms of either polarity to allow speed and direction control of motors.
Device Power 4
Build HAT Serial Protocol
On-board Controllers
The firmware implements an independent controller for the motor power output on each port of the HAT. The controller
can be in one of two modes: 'direct PWM' (the default) and 'PID'. In addition, each controller has an associated setpoint,
which can be constant or varying: see the set command below.
In direct PWM mode the setpoint, which must be in the range from –1 to +1, directly controls the power output. This is
useful in simple motor applications, for driving lights, and for certain devices that use 'motor power' for other purposes.
Such devices usually need to have power enabled very shortly after connection is established, and usually need to be
powered in reverse: i.e., set –1.
In PID mode a proportional-integral-differential controller reads a value from a sensor: typically this will be a speed or
angle sensor on a motor being controlled. This value is called the 'process variable'. The PID controller adjusts the output
power to attempt to have the process variable track the setpoint closely. Using this you can, for example, attempt to run a
motor at constant speed under varying load, or move a motor to a given position. See the pid command below for more
details.
On-board Controllers 5
Loading...