cocube Core APIs

import cocube

What is this?

cocube is the core module in the CoCube firmware. It is responsible for:

• reading the positioning sensors
• reading left and right wheel speed
• controlling forward, backward, and turning movement
• checking battery level

Constants

cocube.FORWARD
cocube.BACKWARD
cocube.LEFT
cocube.RIGHT

Position and speed

cocube.pos

It refreshes automatically in the background about every 10ms, so you can read the attributes directly.

Attribute	Type	Meaning
cocube.pos.x	int	current X coordinate
cocube.pos.y	int	current Y coordinate
cocube.pos.angle	int	current heading angle
cocube.pos.index	int	current grid index
cocube.pos.state	bool	whether positioning is valid

cocube.speed

Attribute	Type	Meaning
cocube.speed.left	float	left wheel speed
cocube.speed.right	float	right wheel speed

Smallest example:

import time
import cocube

while True:
    if cocube.pos.state:
        print(cocube.pos.x, cocube.pos.y, cocube.pos.angle)
        print(cocube.speed.left, cocube.speed.right)
    else:
        print("Positioning is invalid")
    time.sleep_ms(100)

Basic movement

These APIs are better for quick chassis control:

cocube.set_wheel(left, right)
cocube.move(direction, speed)
cocube.rotate(direction, speed)
cocube.stop()
cocube.brake()
cocube.move_ms(direction, speed, ms)
cocube.rotate_ms(direction, speed, ms)

Notes:

• the commonly used speed range is 0~50
• set_wheel(left, right) supports -50~50
• each set_wheel() call only performs one PID adjustment and returns immediately; if you want continuous speed-feedback correction, call it repeatedly in a loop
• move() and rotate() return immediately and keep the current motor output; you usually stop them later with stop() or brake()
• move_ms() and rotate_ms() update output internally every 10ms and automatically call brake() when time is up

Precise movement

These APIs are better for lesson tasks such as "go to a point" or "turn to an angle":

cocube.rotate_to(angle, speed=30)
cocube.rotate_by(direction, speed, degrees)
cocube.move_to(x, y, speed=40)
cocube.move_by(direction, steps, speed=40)

Notes:

• rotate_to(): blocking, turns to an absolute angle, error about <= 1°
• rotate_by(): blocking, rotates by a relative angle, requires valid cocube.pos.state
• move_to(): blocking, turns first and then moves to the target coordinate with differential correction based on heading error
• move_by(): blocking, moves forward or backward by steps, requires valid cocube.pos.state

Other

cocube.battery()

Returns battery percentage in the range 0~100.

Common pattern

import cocube
import time

cocube.move_ms(cocube.FORWARD, 30, 1000)
time.sleep_ms(300)
cocube.rotate_by(cocube.LEFT, 30, 90)
print(cocube.battery())

Notes

• move_to(), rotate_by(), and move_by() all depend on valid positioning. When pos.state is invalid, the latter two return immediately
• move_to() does not explicitly check pos.state first, but it is only suitable when positioning data is updating normally
• stop() is more like coasting to a stop, while brake() is more like actively braking