socketry

Python API and CLI for controlling Jackery portable power stations.

Reverse-engineered from the Jackery Android APK (v1.0.7) and iOS app (v1.2.0). Communicates via Jackery's cloud MQTT broker and HTTP API — no modifications to the device or its firmware.

Quick start

uvx 'socketry[cli]' login --email you@example.com --password 'yourpass'
uvx 'socketry[cli]' get

Or install it once and use socketry directly:

uv tool install 'socketry[cli]'
socketry login --email you@example.com --password 'yourpass'
socketry get

Supported devices

All 10 models in the current Jackery app share the same protocol:

Properties and MQTT action IDs are exhaustive for this APK version. Unknown properties returned by newer firmware are displayed as raw key/value pairs.

Install

# Install as a CLI tool
uv tool install 'socketry[cli]'

# Or run directly without installing
uvx 'socketry[cli]' --help

# Or install as a library only (no CLI dependencies)
pip install socketry

# Or install with CLI included
pip install 'socketry[cli]'

CLI usage

Login

# Authenticates and discovers all devices (owned + shared with you)
socketry login --email you@example.com --password 'yourpass'

# List devices and select the active one
socketry devices
socketry select 0

Credentials are saved to ~/.config/socketry/credentials.json (mode 0600).

Reading properties (get)

# All properties (colored + grouped on a TTY)
socketry get

# Single property — by CLI name or raw protocol key
socketry get battery          # Battery: 85%
socketry get rb               # Battery: 85% (same thing)
socketry get ac               # AC output: ON

# JSON output (indented on TTY, compact when piped)
socketry get --json
socketry get ac --json        # {"oac": 1}
socketry get --json | jq .rb  # pipe-friendly

Available properties:

Raw protocol keys (rb, oac, bt, ...) are also accepted.

Changing settings (set)

# I/O toggles
socketry set ac on
socketry set dc off
socketry set usb on
socketry set car off

# Light
socketry set light high       # off | low | high | sos

# Device settings
socketry set charge-speed mute      # fast | mute
socketry set battery-protection eco # full | eco
socketry set ups on
socketry set sfc on

# Integer settings
socketry set screen-timeout 30
socketry set auto-shutdown 60
socketry set energy-saving 30

# Wait for device confirmation
socketry set ac on --wait

# Show available settings
socketry set
socketry set light            # "expects a value: off | low | high | sos"

Writable settings:

Sharing devices (share-qr)

# Generate a sharing QR code (expires in 5 minutes)
socketry share-qr

# JSON output
socketry share-qr --json

Another Jackery user can scan the QR code in their Jackery app to gain access to your shared devices.

Watching live updates (watch)

# Stream all property changes in real time
socketry watch

# Filter to a single property
socketry watch battery

# Example output:
# [14:32:01] 855124121010657 Output power (output-power): 182W
# [14:32:05] 855124121010657 Battery (battery): 85%
# [14:32:10] Disconnected, reconnecting...
# [14:32:15] 855124121010657 Battery (battery): 84%

Press Ctrl+C to stop. The connection automatically reconnects if the broker disconnects (e.g. when a set command runs from another terminal).

Note: The Jackery broker only allows one MQTT connection per account. Running socketry set while watch is active will briefly disconnect the watcher. It reconnects automatically, but updates during the reconnection window are lost.

Library usage

import asyncio
from socketry import Client

async def main():
    # Authenticate (or load saved credentials)
    client = await Client.login("email@example.com", "password")
    client.save_credentials()

    # Or load previously saved credentials
    client = Client.from_saved()

    # List and select devices
    devices = await client.fetch_devices()
    client.select_device(0)

    # Read properties
    props = await client.get_all_properties()
    setting, value = await client.get_property("battery")
    print(f"{setting.name}: {setting.format_value(value)}")

    # Control
    await client.set_property("ac", "on")
    result = await client.set_property("light", "high", wait=True)

    # Generate a sharing QR code
    qr = await client.generate_share_qrcode()
    print(f"QR Code ID: {qr['qrCodeId']}")

    # Subscribe to real-time updates
    async def on_update(device_sn: str, properties: dict) -> None:
        print(f"{device_sn}: {properties}")

    async def on_disconnect() -> None:
        print("Reconnecting...")

    subscription = await client.subscribe(on_update, on_disconnect=on_disconnect)
    # ... later
    await subscription.stop()

asyncio.run(main())

How it works

socketry ──HTTP──> iot.jackeryapp.com    (login, device list, properties)
socketry ──MQTT──> emqx.jackeryapp.com  (device control via encrypted TLS)

Login uses AES-192/ECB + RSA-1024 encrypted HTTP POST. Device control commands are published over MQTT (TLS 1.2 with a self-signed CA). Status polling uses the HTTP property endpoint. See docs/protocol.md for the full protocol specification.

Roadmap

• MQTT real-time monitor (socketry watch + client.subscribe())
• Token auto-refresh (JWT expires ~30 days)

License

MIT