BrickPi documentation, redux: API definition needed

BrickPi
1

Folks, have read the post from earlier this year (BrickPi documentation), especially JohnC’s response. Is there any update, or is it still the case that there is not an official API description for the Python programming interface for BrickPi? If not, I highly recommend that someone take a crack at writing such a document.

I know sample code is available. It’s helpful, but not exhaustive in describing how the various device controls can be used. And, yes, the source code for the Python library is available, but understanding it requires reverse engineering that code and the “firmware” on the two Arduino processors on the BrickPi board, even all the way back to reverse engineering the Lego hardware, certainly not a worthwhile endeavor.

For example, In the case of moving the large motor, it appears that all rotation arguments are treated as integer degrees. Is this consistent with the physical resolution of the optical sensor in the Lego motor? If not, roundoff errors can accumulate over multiple moves. Is it possible to read the current motor position? (Didn’t see a function for that.) If it is, is it absolute or relative (to the power-on position). {Note: the Lego EV3 programming environment provides a motor position reader function and a reset function, which is not definitive on the relative vs. absolute question). Also, the motor driver code uses a reverse-direction current pulse of specified time duration to bring a moving motor to a stop. The duration is hard-coded in the driver. Why isn’t it exposed via the Python API? I suspect it needs to be modified under different load and power conditions.

For the sensors, questions abound, both about the raw performance of the Lego devices and how their output is handled by the BrickPi device and library.

In summary, kudos on a great device with great promise, but apparently limited by a lack of documentation. Am I missing something here?

TIA,

Mike

2

It sounds like you are using BrickPi+, but for the BrickPi3 the Python drivers are documented with docstrings. With BrickPi3 installed, you can run this from the command line to view the documentation for the BrickPi3 class:

pydoc brickpi3.BrickPi3

Regarding the motor encoders, Lego Mindstorms motors support 720 ticks per rotation (quadrature encoders with 180 full cycles per rotation). The BrickPi+ motor encoder units are 0.5 degrees (the microcontroller interrupts on every line change of both signals). The BrickPi3 (like the NXT and EV3) interrupts on line changes from one signal, and uses the other signal as a direction indicator, so it has a native resolution of 1 degree (no scaling).

Since the motors use quadrature encoders, there’s no reference to absolute position (Lego motor hardware design). Whatever position the motor is in when either the motor gets plugged in or the robot powers up, is considered 0 (applies to BrickPi+, BrickPi3, NXT, and EV3). You can reset or offset the encoder value if necessary.

Regarding Lego sensors, there is existing documentation elsewhere describing how they work. We show how to use Lego sensors with the BrickPi, but we don’t sell or otherwise document Lego sensors.

1 Like
3

Matt,

Thanks for the prompt and informative reply. Please see my responses and questions interspersed below.

Matt http://forum.dexterindustries.com/u/matt Dexter Industries Engineer
June 13
It sounds like you are using BrickPi+, but for the BrickPi3 the Python drivers are documented with docstrings.

My bad. Looks like I installed the latest Raspbian (2017.04.02_Dexter_Industries_jessie.img) image on our BrickPi3. So far, so good. But I’ve been doing most of my Python code exploration on my MacBook Pro using a clone of your BrickPi (i.e., BrickPi+) GitHub repo, instead of the newer BrickPi3 repo. Sigh… (Suggestion: put a note in the BrickPi repo README that it only applies to earlier hardware.)

With BrickPi3 installed, you can run this from the command line to view the documentation for the BrickPi3 class:

pydoc brickpi3.BrickPi3
Since it’s more convenient for me to work from my MacBook Pro, can I do a (partial?) install of BrickPi3 for Python on MacOS (latest Sierra, with Python and Brew installed), so that I can review the Python code and docs there?

Regarding the motor encoders, Lego Mindstorms motors support 720 ticks per rotation (quadrature encoders with 180 full cycles per rotation). The BrickPi+ motor encoder units are 0.5 degrees (the microcontroller interrupts on every line change of both signals). The BrickPi3 (like the NXT and EV3) interrupts on line changes from one signal, and uses the other signal as a direction indicator, so it has a native resolution of 1 degree (no scaling).

Understand: "180 encoder plate cycles per rev” x 4 “AB state changes”/cycle = 720 “AB state changes”/rev. If you only monitor A for state changes, then you only get 360 state changes per rev and the state of B at each indicates direction of motion.

Since the motors use quadrature encoders, there’s no reference to absolute position (Lego motor hardware design). Whatever position the motor is in when either the motor gets plugged in or the robot powers up, is considered 0 (applies to BrickPi+, BrickPi3, NXT, and EV3). You can reset or offset the encoder value if necessary.

Yup, what I expected (without a separate optical track or fancier electronics to look for fiducials/skips in the AB optical tracks) to establish an absolute reference.

Regarding Lego sensors, there is existing documentation elsewhere describing how they work. We show how to use Lego sensors with the BrickPi, but we don’t sell or otherwise document Lego sensors.

Will look for it. Any pointers to especially reliable info?

Additional questions:
Does the above description of optical encoder behavior apply to the medium size motor as well, i.e., does it also have a 720 click/rev optical encoder?
I presume the power level argument for motor commands is integer, 0-100, which is directly used as a PWM on-time percentage by the driver.
Are there any published (or reverse engineered) mechanical performance specs for the motors, i.e., speed/torque curves at fixed voltage(s), current/torque curves? Data points if not full curves, i.e., unloaded speed and current, stalled torque and current? Gear train ratio? Gear train backlash, e.g., in degrees (either motor or driven axle).
Recommended BrickPi power supply (probably in your docs, but might as well ask)
In the BrickPI+ repo version, I saw what looked like some experimental Python code for multi-threading. What’s the status of this support in BrickPI3?

Anything I can do to help you out? (Assume I’m a competent CS, EE and ME, but new to this particular HW & SW :slight_smile:

Thanks again,

Mike

4

Hi Mike,

I added a note in the BrickPi README directing BrickPi3 users to the BrickPi3 repo.

You can SSH into the RPi from a different computer. On Windows, putty works well. On Mac or Linux, I think you can SSH directly from the command line. This is very handy for using the RPi from the convenience of a laptop or workstation. I haven’t used a keyboard, mouse, or monitor with a RPi in probably a year or so.

Regarding installing BrickPi3 on a Mac, I’m not sure. You’d want to run setup.py to install the python modules, but you wouldn’t want to run the install.sh script since that changes RPi configuration (enable SPI, install OpenOCD, etc. since those are only relevant if you’re using the BrickPi3 hardware).

The EV3 medium motor does indeed have the same number of encoder ticks per output rotation.

Power level is an integer that sets the driver PWM percentage. It’s basically 0-100 (percent), but it’s signed, so it’s actually -100 to 100 (full backwards to full forwards). If you set the power to anything outside that range (e.g. -128 or 127) the motors will float (rotate freely as if they were disconnected).

Regarding motor specs, take a look at Philo’s documentation.

For sensor descriptions, see here (NXT sensors) and here (EV3 sensors). For schematics and other technical information, you can download the NXT and EV3 Hardware Developer Kits from here. For an extensive list of sensors supported by ev3dev (only some of which are already/natively supported by the BrickPi3 with Python), see here. In that list, click on the name in the “Name” column to see the modes and data fields for each sensor.

Regarding multi-threading, we don’t have Python support. You could add support to your user program by wrapping the BrickPi3 calls in mutexes. Since each of the RPi<>BrickPi3 commands/communications is handled by a single SPI transaction, I don’t think you even need mutexes (spidev/Linux should just do one transaction at a time, and the messages shouldn’t conflict).

Matt

5

Matt,

Great info! Thanks!

Mike

6