Confused about orientation

[egolombek]

I am really brand new to pybricks, and am struggling getting going. Our FLL robot has our Spike Prime hub mounted -90 degrees from the usual meaning the Bluetooth button is on the left, the start button is on the right, and the BDF ports are forward. We are using block programming, and the block we used is: top side axis z - front side axis -y. Is this correct? Or, should it be just y? Or something else? We have tried both, and drive base use gyro, does not seem to work with drive straight. Any help would be most appreciated. :-)

[laurensvalk]

If you're just using the gyro to make turns or drive straight, then you don't need any adjustments for this orientation.

If it's spinning out of control, you may want to check the motor port selection instead. It's important that left is truly on the left and right is on the right.

Otherwise, it will attempt to compensate but only drive further in the wrong way, and eventually it just spins.

If in doubt, do some basics turns without the gyro first. Test that positive distances make it go forward and positive turns make it steer to the right (clockwise when viewed from the top).

[egolombek]

Thanks for your reply. The robot is veering left. It could be an issue with one of the motors or the robot design, I suppose, but the gyro should theoretically correct for this, I think.

[MrGibbage]

Future readers: this is all wrong. Read below for correct information.

Just going to add my $0.02, if that is OK. The documentation for this is confusing to me. It's not wrong. It's just not written in a way that made sense to me.
https://docs.pybricks.com/en/latest/signaltypes.html#reference-frames

The way I think of it now, you could write +Z on the top of your hub, and -Z on the bottom. And so could I. And so could everyone else. This is the Z Axis and it is the same for everyone, regardless of how it is installed on their robot. Continuing, and using this image https://docs.pybricks.com/en/latest/_images/imuexamples.png, the leftmost robot in that image has a line pointing to the hub with the label "front_side = Axis.X". That is the +X (the side with the charging port), and the opposite small side (with the speaker) is the -X. Using that same picture (the robot on the left side), the long side that you can see (ports B, D & F), that is the +Y side, and the side that you can't see in the picture, that is the -Y side. Like I said, we could all write those on our hub because it doesn't matter how it is installed on our robot. Now, when declaring a PrimeHub object in pybricks, we can tell it which axis is pointing to the top of your robot, and which axis is pointing to the front. So in your case, your top_side is Axis.Z, and your front side is +Y.

Now that I have written this, I wonder if I have my Y axis backwards? The docs say Y positive is to the left, which would mean I have been declaring our robots incorrectly for several years. I hope I got this right!

What I would love in the docs would be in addition to the current picture, add four labeled pictures with the screen side up, and each of the four possible orientations, since those are probably the four most common installations.

[egolombek]

So, you agree: top side axis z - front side axis -y ?

[dlech]

If you initialize the hub with top_side=Axis.Z, that means the buttons are facing up away from and are parallel to the ground. (The "top" side is always the side with the buttons regardless of how the hub is oriented.)

If you initialize the hub with front_side=-Axis.Y, it means that the side with the USB port is going to be the right side of the robot. (The "front" side is always the the side with the USB port, no matter which way the hub is oriented.)

So the driving directions would be as pictured:

But in the original description, it sounds like you want front_side=Axis.Y so that it is the left side, rather than the right side. That would also swap forwards and backwards directions.

[MrGibbage]

Ooooohhhhh! Now I see! Thanks so much for clarifying this. My post from a couple of hours ago was quite wrong (I updated it for future travelers). I think what you wrote makes so much more sense. To put this another way (and this really is just repeating what @dlech wrote), we could all write "top_side" on the white side of our hubs (the side with the buttons), and we could all write "front_side" on the side with the USB port. That will be true for all of us, no matter how our hub is installed. We can then look at the axes here: https://docs.pybricks.com/en/latest/_images/imuexamples.png. For most of us, our installed hub in our robot, the top_side will be pointing in the +Z direction. That means toward the sky. Then it's just a matter of looking where your usb port is. Forward in the hub orientation drawing is to the right. In my case, our usb port is on the right side of our robot, which is the -Y axis, so lucky us, we have been declaring our PrimeHub correctly: top_side=Axis.Z, front_side=-Axis.Y.

https://github.com/FLL-Team-24277/FLL-Fall-2025-Unearthed/blob/main/help/github/images/Robot_summer_2023_CompetitionBot.png
Here, the robot Front is the side we see, coming toward us.

Please tell me that I have this straight now :)

[dlech]

Yes, you got it now. 😄

I think the technical name for this is "frame of reference". The top_side and front_side are according to the hub's reference frame. Like you said, we could write these on the hub because the never change with reference to the hub. This is also the reference frame of the IMU since it is built into the hub.

The X/Y/Z axes are according to the robots reference frame. Once the robot is built, you could write those on the robot and they won't change as (long as you don't rebuild the robot).

The initialization arguments top_side=Axis.Z, front_side=Axis.Y are telling the software how to translate from one reference frame (the IMU's) to the other (the robot's).