### Install Project with Poetry

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Installs the project and its dependencies using Poetry. This command also performs an editable install, making the project ready for immediate use.

```bash
poetry install
```

--------------------------------

### Install Dependencies

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Installs project dependencies using uv.

```bash
uv sync
```

--------------------------------

### Install PyMammotion using pip

Source: https://github.com/mikey0000/pymammotion/blob/main/README.md

Install the PyMammotion library using pip. This is the standard method for adding the library to your Python environment.

```bash
pip install pymammotion
```

--------------------------------

### Java AES Encryption Example

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Example of AES encryption used within the app for sensitive data. Requires specific keys and initialization vectors.

```java
SecretKeySpec secretKeySpec = new SecretKeySpec(str2.getBytes(), BreezeCipher.ALGORITHM_AES);
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        cipher.init(1, secretKeySpec, new IvParameterSpec(str3.getBytes()));
        return Base64.encodeToString(cipher.doFinal(str.getBytes()), 2);
```

--------------------------------

### Retrieve Available Areas API Response

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Example response body for retrieving available areas. Includes area names, codes, and ISO codes.

```json
{
    "code": 0,
    "data": [
        {
            "areaCnName": "美国",
            "areaEnName": "United States of America",
            "code": "1",
            "domainAbbreviation": "US",
            "id": "1524591956582207515",
            "isoCode": "USA",
            "pinyin": "MeiGuo"
        },
        ...and many more...
    ],
    "msg": "Request success"
}
```

--------------------------------

### GET /area (retrieve available areas)

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Retrieves a list of available geographical areas, including their names and codes.

```APIDOC
## GET /area (retrieve available areas)

### Description
Fetches a list of available geographical areas, which can be used to specify the `areaCode` during user registration.

### Method
GET

### Endpoint
`https://domestic.mammotion.com/user-server/v1/area`

### Response
#### Success Response (200)
- **code** (integer) - Request status code.
- **data** (array) - A list of area objects.
  - **areaCnName** (string) - Area name in Chinese.
  - **areaEnName** (string) - Area name in English.
  - **code** (string) - Internal area code.
  - **domainAbbreviation** (string) - Domain abbreviation for the area.
  - **id** (string) - Unique identifier for the area.
  - **isoCode** (string) - ISO standard code for the area.
  - **pinyin** (string) - Pinyin representation of the area name.
- **msg** (string) - Request message.

#### Response Example
```json
{
    "code": 0,
    "data": [
        {
            "areaCnName": "美国",
            "areaEnName": "United States of America",
            "code": "1",
            "domainAbbreviation": "US",
            "id": "1524591956582207515",
            "isoCode": "USA",
            "pinyin": "MeiGuo"
        }
    ],
    "msg": "Request success"
}
```
```

--------------------------------

### Build Project Package

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Builds the project package using Poetry. This command creates distributable artifacts for the project.

```bash
poetry build
```

--------------------------------

### Generate Type Hints from Protobuf

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Generates Python type hint files (.pyi) from Protocol Buffer definitions using protoc. This aids in static type checking for Protobuf-generated code.

```bash
poetry run protoc -I=. --python_out=. --pyi_out=. ./pymammotion/proto/*.proto
```

--------------------------------

### Generate MQTT Credentials for Alibaba Cloud IoT

Source: https://github.com/mikey0000/pymammotion/wiki/MQTT

This Python snippet demonstrates how to generate the MQTT client ID, username, and password required for connecting to Alibaba Cloud IoT. Ensure you have your product key, device name, and device secret.

```python
product_key = ...
device_name = ...
device_secret = ...
client_id = "asdf"

mqtt_client_id = f"{client_id}|securemode=2,signmethod=hmacsha1|"
mqtt_username = f"{device_name}&{product_key}"
sign_content = f"clientId{client_id}deviceName{device_name}productKey{product_key}"
mqtt_password = hmac.new(
    device_secret.encode("utf-8"), sign_content.encode("utf-8"),
    hashlib.sha1
).hexdigest()
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Executes all pre-commit hooks across the entire repository. This ensures that code adheres to project standards before committing.

```bash
poetry run pre-commit run --all-files
```

--------------------------------

### POST /email/register (register account)

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Registers a new user account using the provided details and a verification code obtained from the `/email/register/code` endpoint.

```APIDOC
## POST /email/register (register account)

### Description
Creates a new user account. Requires a verification code previously obtained via the `/email/register/code` endpoint and an `areaCode` from the `/area` endpoint.

### Method
POST

### Endpoint
`https://domestic.mammotion.com/user-server/v1/email/register`

### Parameters
#### Request Body
- **areaCode** (string) - Required - The area code obtained from the `/area` endpoint.
- **email** (string) - Required - The user's email address.
- **fullName** (string) - Required - The user's full name.
- **password** (string) - Required - The user's password.
- **verificationCode** (integer) - Required - The verification code sent to the user's email.

### Request Example
```json
{
    "areaCode": "USA",
    "email": "user@example.com",
    "fullName": "John Doe",
    "password": "Password123!",
    "verificationCode": 123456
}
```

### Response
#### Success Response (200)
- **code** (integer) - Request status code.
- **data** (object) - Contains information about the newly registered user.
  - **areaCode** (string) - The area code of the user.
  - **createTime** (string) - The time the account was created.
  - **domainAbbreviation** (string) - Domain abbreviation.
  - **email** (string) - User's email address.
  - **id** (string) - Unique identifier for the user.
  - **registerTime** (string) - The time of registration.
  - **userId** (string) - User's unique ID.
- **msg** (string) - Request message.

#### Error Response (500)
- **code** (integer) - Error status code.
- **msg** (string) - Error message indicating an invalid area code.

#### Error Response (40302)
- **code** (integer) - Error status code.
- **msg** (string) - Error message indicating an invalid password format.

#### Error Response (40200)
- **code** (integer) - Error status code.
- **msg** (string) - Error message indicating an invalid or expired verification code.

#### Response Example (Success)
```json
{
    "code": 0,
    "data": {
        "areaCode": "USA",
        "createTime": "<createTime>",
        "domainAbbreviation": "SE",
        "email": "user@example.com",
        "id": "<id?>",
        "registerTime": "<registerTime>",
        "userId": "<userId>"
    },
    "msg": "Request success"
}
```

#### Response Example (Invalid Area Code)
```json
{
    "code": 500,
    "msg": "Area information does not exist."
}
```

#### Response Example (Invalid Password Format)
```json
{
    "code": 40302,
    "msg": "The password needs 8-16 digits, including at least any two types of letters, numbers and special characters."
}
```

#### Response Example (Invalid Verification Code)
```json
{
    "code": 40200,
    "msg": "The verification code is invalid or expired, please reacquire"
}
```
```

--------------------------------

### Run Single Test File

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Executes a specific test file using the Python interpreter.

```bash
uv run python tests/login_test.py
```

--------------------------------

### Run a Specific Test File

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Executes a specific test file using Poetry. This is useful for running individual tests during development.

```bash
poetry run python tests/test2_instance.py
```

--------------------------------

### Lint and Format Code

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Applies linting and formatting rules using Ruff.

```bash
uv run ruff check --fix pymammotion/
uv run ruff format pymammotion/
```

--------------------------------

### Mammotion App Communication Pathways Diagram

Source: https://github.com/mikey0000/pymammotion/wiki/Reverse-engineering

A C4 context diagram illustrating the communication flow between the App, Luba, Mammotion, and Alibaba Cloud IoT. Useful for understanding system architecture.

```mermaid
C4Context
    System(App, "App")
    System(Luba, "Luba")
    System(Mammotion, "Mammotion")
    System(AlibabaIoT, "Alibaba Cloud IoT")
    BiRel(App, Luba, "Local control", "BLE/MQTT/CoAP")
    Rel(App, Mammotion, "Login", "HTTP")
    Rel(App, Mammotion, "Manage tasks, jobs, etc.", "HTTP")
    BiRel(Luba, AlibabaIoT, "Remote control", "MQTT")
    BiRel(App, AlibabaIoT, "Remote control", "MQTT")
    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="2")
```

--------------------------------

### POST /user/oauth/token (login)

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Obtains an access token for user authentication. Plain text credentials can be used, or they can be AES encrypted.

```APIDOC
## POST /user/oauth/token (login)

### Description
Authenticates a user and returns an access token, refresh token, and user information. Credentials can be sent as plain text or AES encrypted.

### Method
POST

### Endpoint
`https://domestic.mammotion.com/user-server/v1/user/oauth/token`

### Parameters
#### Query Parameters
- **username** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.
- **client_id** (string) - Required - Client identifier.
- **client_secret** (string) - Required - Client secret.
- **grant_type** (string) - Required - Should be `password`.

### Request Example
```json
{
  "example": "https://domestic.mammotion.com/user-server/v1/user/oauth/token?username=user@example.com&password=password123&client_id=MADKALUBAS&client_secret=GshzGRZJjuMUgd2sYHM7&grant_type=password"
}
```

### Response
#### Success Response (200)
- **code** (integer) - Request status code.
- **data** (object) - Contains authentication tokens and user details.
  - **access_token** (string) - The JWT access token.
  - **token_type** (string) - Type of the token, usually `bearer`.
  - **refresh_token** (string) - Token to refresh the access token.
  - **expires_in** (integer) - Token expiration time in seconds.
  - **scope** (string) - Granted scope.
  - **grant_type** (string) - The grant type used.
  - **authorization_code** (string) - Authorization code.
  - **userInformation** (object) - User-specific information.
    - **areaCode** (string) - User's area code.
    - **domainAbbreviation** (string) - Domain abbreviation.
    - **email** (string) - User's email.
    - **gender** (string) - User's gender.
    - **userId** (string) - User's unique ID.
  - **jti** (string) - JWT ID.
- **msg** (string) - Request message.

#### Response Example
```json
{
    "code": 0,
    "data": {
        "access_token": "<access_token>",
        "token_type": "bearer",
        "refresh_token": "<refresh_token>",
        "expires_in": 1295999,
        "scope": "read",
        "grant_type": "password",
        "authorization_code": "<authorization_code>",
        "userInformation": {
            "areaCode": "SWE",
            "domainAbbreviation": "SE",
            "email": "<email>",
            "gender": "0",
            "userId": "<userId>"
        },
        "jti": "<jti>"
    },
    "msg": "Request success"
}
```
```

--------------------------------

### Key Java Files for Protocol Research

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Lists important Java files within the decompiled APK source that are critical for researching the Mammotion protocol, device logic, and command structures.

```text
mvp/fieldmower/device/HashDataManager.java — map/hash/line/cover-path fetch logic, clearing conditions, retry logic
```

```text
mvp/fieldmower/device/MACarDataManager.java — incoming message parsing, device state callbacks, calls to HashDataManager
```

```text
mvp/fieldmower/device/MACommandHelper.java — outgoing command builders (field-mower variant)
```

```text
command/MACommandHelper.java — outgoing command builders (top-level variant)
```

```text
proto/MctrlNav.java — nav protobuf definitions
```

```text
proto/MctrlSys.java — sys/report protobuf definitions (device status, work report fields)
```

--------------------------------

### Incoming Message Flow

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Illustrates the sequence of operations when a raw message is received, from decoding to state updates and event emission. This flow is crucial for understanding how device state is managed and how events are propagated.

```text
Transport.on_message(raw bytes)
  → DeviceHandle._on_raw_message()
      1. Decode bytes → LubaMsg
      2. StateReducer.apply(current, msg) → new MowingDevice  (pure)
      3. DeviceStateMachine.apply(new_device) → snapshot + changed
      4. Emit snapshot to state_changed_bus (HA subscribes here)
      5. DeviceMessageBroker.on_message(luba_msg)
           ├─ solicited  → resolve pending future
           └─ unsolicited → EventBus.emit (sagas / subscribers)
```

--------------------------------

### Generate Python Models from Protobuf

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Generates Python model files from Protocol Buffer definitions using protoc. This command is used to create data structures based on .proto files.

```bash
poetry run protoc -I=. --python_out=. --python_betterproto_out=. ./pymammotion/proto/*.proto
```

--------------------------------

### Decoding Protobuf Messages with protoc

Source: https://github.com/mikey0000/pymammotion/wiki/Protobuf

This bash command demonstrates how to decode a raw Protobuf message using `protoc`. It pipes a hex-encoded message through `xxd` to binary, then decodes it using a specified proto file and message type. Useful for verifying decoded messages against proto definitions.

```bash
echo 08f8011001180730013880802042020801 | xxd -r -p | protoc --proto_path=/home/michael/git/pyluba/ --decode LubaMsg pyluba/proto/luba_msg.proto
```

--------------------------------

### Additional Linting

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Runs additional linting checks using pylint.

```bash
uv run pylint pymammotion/
```

--------------------------------

### Regenerate Protobuf Code

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Regenerates Python protobuf code from .proto files. The CI process verifies this output.

```bash
uv run protoc -I=. --python_out=. --python_betterproto2_out=pymammotion/proto ./pymammotion/proto/*.proto
```

--------------------------------

### Run Mypy Type Checking

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Executes Mypy for static type checking on a specified file. This helps catch type errors before runtime.

```bash
poetry run mypy {filename}
```

--------------------------------

### POST /email/register/code (request registration code)

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Requests a verification code to be sent to the specified email address for account registration.

```APIDOC
## POST /email/register/code (request registration code)

### Description
Sends a verification code to the specified email address, which is required for account registration.

### Method
POST

### Endpoint
`https://domestic.mammotion.com/user-server/v1/email/register/code`

### Parameters
#### Query Parameters
- **email** (string) - Required - The user's email address.

### Response
#### Success Response (200)
- **code** (integer) - Request status code.
- **data** (boolean) - Indicates if the request was successful.
- **msg** (string) - Request message.

#### Response Example
```json
{
    "code": 0,
    "data": true,
    "msg": "Request success"
}
```
```

--------------------------------

### Register Account API Success Response

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Successful response body for account registration. Includes user details and creation timestamps.

```json
{
    "code": 0,
    "data": {
        "areaCode": "<areaCode",
        "createTime": "<createTime>",
        "domainAbbreviation": "SE",
        "email": "<email>",
        "id": "<id?>",
        "registerTime": "<registerTime>",
        "userId": "<userId>"
    },
    "msg": "Request success"
}
```

--------------------------------

### Generate Python Protobuf Code

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Generates Python code from Protocol Buffer definitions using protoc. This command is used for creating Python classes that represent Protobuf messages.

```bash
poetry run protoc -I=. --python_out=. --python_out=. ./pymammotion/proto/*.proto
```

--------------------------------

### Run Pylint Code Analysis

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Runs Pylint to analyze Python code for errors and style issues. This command provides a comprehensive report on code quality.

```bash
poetry run pylint pyluba
```

--------------------------------

### Decompiled APK Source Paths

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Provides the file paths to decompiled APK source code for different Mammotion versions, useful for reverse engineering and understanding the underlying protocol and logic.

```text
/home/michael/Downloads/Mammotion_2.2.4.13_APKPure/com.agilexrobotics/java_src/com/agilexrobotics/
```

```text
/home/michael/Downloads/mammotion-2-3-8-201/agilex/java_src/com/agilexrobotics/
```

--------------------------------

### Bump Project Version (Patch)

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Increments the patch version of the project. This script is used for managing project releases.

```bash
./bin/bumpver update --patch
```

--------------------------------

### Java Class Structure for Protobuf

Source: https://github.com/mikey0000/pymammotion/wiki/Protobuf

This Java code snippet shows the structure of a Protobuf generated class, including field definitions and serialVersionUID. It is typically found within decompiled APKs and serves as a basis for reverse engineering proto definitions.

```java
public static final class baseInfo extends GeneratedMessageV3 implements baseInfoOrBuilder {
    public static final int BATT_VAL_FIELD_NUMBER = 3;
    public static final int DEV_STATUS_FIELD_NUMBER = 2;
    public static final int DEV_VERSION_FIELD_NUMBER = 1;
    public static final int INIT_STATUS_FIELD_NUMBER = 4;
    public static final int IS_TILT_FIELD_NUMBER = 5;
    private static final long serialVersionUID = 0;
    private int battVal_;

```

--------------------------------

### Decoding Raw Protobuf Messages with protoc

Source: https://github.com/mikey0000/pymammotion/wiki/Protobuf

This bash command decodes a raw Protobuf message without referencing a specific .proto file. It's useful for inspecting the structure of unknown or partially reverse-engineered messages. The message is piped from hex to binary via `xxd`.

```bash
echo 08f8011001180730013880802042020801 | xxd -r -p | protoc --proto_path=/home/michael/git/pyluba/ --decode_raw
```

--------------------------------

### POST /user/oauth/check

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Checks the validity of the current authentication token.

```APIDOC
## POST /user/oauth/check

### Description
Verifies if the provided access token is valid and the user is currently logged in.

### Method
POST

### Endpoint
`https://domestic.mammotion.com/user-server/v1/user/oauth/check`

### Authentication
Requires authentication via `Authorization: Bearer <access-token>` header.

### Response
#### Success Response (200)
- **code** (integer) - Request status code.
- **data** (boolean) - `true` if the token is valid and the user is logged in, `false` otherwise.
- **msg** (string) - Request message.

#### Response Example
```json
{
    "code": 0,
    "data": true,
    "msg": "Request success"
}
```
```

--------------------------------

### User Login API Response

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Successful response body for the user login endpoint. Contains access tokens and user information.

```json
{
    "code": 0,
    "data": {
        "access_token": "<access_token>",
        "token_type": "bearer",
        "refresh_token": "<refresh_token>",
        "expires_in": 1295999,
        "scope": "read",
        "grant_type": "password",
        "authorization_code": "<authorization_code>",
        "userInformation": {
            "areaCode": "SWE",
            "domainAbbreviation": "SE",
            "email": "<email>",
            "gender": "0",
            "userId": "<userId>"
        },
        "jti": "<jti>"
    },
    "msg": "Request success"
}
```

--------------------------------

### Run Ruff Check and Fix

Source: https://github.com/mikey0000/pymammotion/blob/main/scripts.txt

Runs the Ruff linter to check for code style issues and automatically fixes them. This command helps maintain code quality and consistency.

```bash
poetry run ruff check --fix
```

--------------------------------

### Register Account API Request Body

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

JSON body structure for registering a new account. Requires area code, email, name, password, and verification code.

```json
{
    "areaCode": "<areaCode>",
    "email": "<email>",
    "fullName": "<name>",
    "password": "<password",
    "verificationCode": <verification_code>
}
```

--------------------------------

### Register Account API Error Response (Invalid Password Format)

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Error response indicating an invalid password format during account registration. Specifies password requirements.

```json
{
    "code": 40302,
    "msg": "The password needs 8-16 digits, including at least any two types of letters, numbers and special characters."
}
```

--------------------------------

### Type Checking

Source: https://github.com/mikey0000/pymammotion/blob/main/CLAUDE.md

Performs type checking on the specified directory using ty. Excludes certain subdirectories as configured in pyproject.toml.

```bash
uv run ty check pymammotion/
```

--------------------------------

### Register Account API Error Response (Invalid Verification Code)

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Error response when an invalid or expired verification code is used for account registration.

```json
{
    "code": 40200,
    "msg": "The verification code is invalid or expired, please reacquire"
}
```

--------------------------------

### Request Registration Code API Response

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Successful response for requesting a registration code via email. Indicates that an email with a code has been sent.

```json
{
    "code": 0,
    "data": true,
    "msg": "Request success"
}
```

--------------------------------

### Register Account API Error Response (Invalid Area Code)

Source: https://github.com/mikey0000/pymammotion/wiki/user-HTTP-API

Error response when an invalid area code is provided during account registration.

```json
{
    "code": 500,
    "msg": "Area information does not exist."
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.