# MindCub3r

LEGO EV3 robot that solves a Rubik's Cube, with a laptop simulator.

## Project structure

```
Speedcube_Shuffler/
├── main.py              # entry point — simulator by default, --robot flag for EV3
├── scramble.py          # run a scramble directly on the physical robot
├── demo.py              # test basic motor movements on EV3
├── scan_faces.py        # scan all 6 face colours using the EV3 colour sensor
├── double_flip.py       # test double-flip sequence on EV3
├── cube/
│   ├── state.py         # apply scrambles, read face grids from PyCuber
│   ├── display.py       # print csTimer-style layout
│   └── solver.py        # CFOP solver (not yet implemented)
├── robot/
│   ├── motor.py         # EV3 motor commands (EV3 only)
│   ├── move_mapper.py   # WCA moves → physical robot action sequences
│   ├── orientation.py   # tracks cube orientation across tilts/spins
│   └── scanner.py       # EV3 colour sensor → cube state (EV3 only)
├── simulator/
│   └── runner.py        # interactive laptop simulator (no hardware needed)
├── calibration/         # EV3 calibration and utility scripts
│   ├── calibrate.py
│   ├── free.py
│   ├── free_motors.py
│   └── reset_arm.py
└── test/                # hardware test scripts


Speedcube_Shuffler/
├── main.py              # entry point: simulator by default, --robot for EV3
├── scramble.py          # direct entry point for physical robot execution
├── cube/
│   ├── state.py         # cube state representation (built on PyCuber)
│   └── display.py       # csTimer-style visual layout
├── robot/
│   ├── motor.py         # primitive motor actions and calibration constants
│   ├── move_mapper.py   # naive baseline: WCA moves → fixed action sequences
│   └── orientation.py   # orientation state machine and action planner
└── simulator/
    └── runner.py        # interactive laptop simulator (no hardware required)

    
```

## Setup

```bash
pip install pycuber
```

## Run the simulator (laptop)

```bash
python main.py
```

The simulator lets you enter WCA scrambles and see the resulting cube state and the list of robot actions that would be executed.

## Run on the EV3

Copy the repo to the EV3 brick, then run scripts directly:

```bash
# Execute a scramble on the robot
python scramble.py

# Scan all 6 faces for colour calibration
python scan_faces.py

# Quick motor test
python demo.py
```

## Orientation

All scrambles and displays use **White on top, Green in front** — matching csTimer's default.
This is also PyCuber's default solved state, so no remapping is needed.

## How the robot works

1. The cube sits on a **turntable** (Output B) that spins the bottom layer.
2. A **tilt arm** (Output A) grips and tilts the cube to bring any face to the bottom.
3. A **scanner arm** (Output C) sweeps the colour sensor over the top face.

`robot/orientation.py` tracks which colour is on which face after each tilt and spin, so `scramble.py` always knows how to reorient the cube before turning a given face.

## Key PyCuber facts

- `cube["U"]` → returns a Centre **cubie** object, NOT a face grid
- `cube.get_face("U")` → returns a 3×3 list of Square objects ✓
- `Square.colour` → full English name: `"white"`, `"yellow"`, etc.
- Use `COLOUR_MAP` in `cube/state.py` to convert to single letters

## What's implemented

- [x] Scramble input and cube state display
- [x] csTimer-style 54-sticker layout
- [x] WCA move → robot action mapping (`move_mapper.py`)
- [x] Orientation tracking across tilts and spins (`orientation.py`)
- [x] EV3 motor execution (`motor.py`, `scramble.py`)
- [x] Colour sensor face scanning (`scan_faces.py`)
- [ ] Full cube state read from sensor (54-sticker scan)
- [ ] CFOP solver