User Tools

Site Tools


cfwbuilder

ScooterHacking Custom Firmware API documentation

The ScooterHacking Custom Firmware API is available at api.cfw.sh.

Requests are formed as follow: api.cfw.sh/scooterIdentifier?parametersChain

Scooter models table

Scooter modelPatcher statescooterIdentifier value(case sensitive)
Ninebot ESxOnlineesx
Ninebot MaxOnlinemax
Ninebot E2xWIPe2x (might change before release)
Xiaomi M365OutdatedN/A (non-migrated)
Xiaomi M365 ProOutdatedN/A (non-migrated)
Xiaomi 1SOnline (beta)1s
Xiaomi M365 Pro 2Online (beta)pro2

GET parameters

To build your parameter chain, you can use any of the available GET parameters listed below.
Some parameters requiring more details about their working behavior will have their own table of values.

✅: patch in production | ❌: no assignee/non-applicable | ⏳: work in progress | ⌛ : the patch is undergoing tests/dev branch only

GET parameterDisplay nameTypeDefault valueAccepted valuesDescriptionESxMax1SPro2
versionFirmware versionstringDRVxxxDRVxxxBase version. See the below table. VALID PARAMETER REQUIRED FOR FILE DOWNLOAD.
outputOutput filestringzip2See the below table.If you want to use another output format for the custom firmware.
nameFilenamestringNone<any ASCII string up to 40chars>Replaces the time-based part of the filename by any custom name.
version_spoofingVersion spoofingboolNone<any string>Sets DRV version higher to prevent an update from overwriting it.
regionScooter regionstringautous, eu, deEnforces firmware region and disables S/N parsing. Also makes sure the ESC accepts S/N change requests (“auto”).
motor_power_constantMPCint5157510000→65535Deprecated way of increasing output power. Won't be added to future patchers.
speed_normal_kmhMax speedint(per model)10→65Sets Sports max speed for no region/US region.
speed_normal_kmh_euMax speed (EU)int2710→65Sets Drive max speed for US region and Sports max speed for EU region.
speed_normal_kmh_deMax speed (DE)int2210→65Sets Drive max speed for EU region and Sports max speed for DE region.
speed_normal_batterySports battery currentint(per model)5000→65535Sets battery current limit for all Sports modes.
speed_drive_batteryDrive battery currentint(per model)5000→65535Sets battery current limit for all Drive modes.
speed_eco_batteryEco battery currentint(per model)5000→65535Sets battery current limit for Eco mode.
direct_power_controlDirect power control statestringoffSee the below table.Direct Power Control changes the throttle algorithm from speed to power-based, like in a thermal-engine vehicle. No speed limit applies while using DPC.
direct_power_control_curveDirect power control curve typestringflatflat; quadraticSets DPC curve type.
no_kersNo KERSboolNone<any string>Disables energy recovery when the throttle is inactive. Clonk-free.
wheel_speed_constWheel Speed Multiplierint8“:390; 10”: 315200→500Don't change if you use stock tires
error_raising_levelError raising levelint00→3https://wiki.scooterhacking.org/doku.php?id=nberrorcodes
no_brake_light_flashStatic brake lightboolNone<any string>Enforces German brake light behavior for other regions.
cruise_control_delayCruise control delayint50→10How many seconds it takes for cruise control to kick in.
cruise_control_nobeepNo cruise control beepboolNone<any string>
motor_start_speedMotor start speedint50→10Minimum speed in km/h before the motor will start.
boot_workmodeForce boot power modeint30: Drive; 1: Eco; 2: Sports; 3: Don't patchEnforces selected power mode at boot.
remove_charging_modeRemove charging modeboolNone<any string>ESC will ignore input from the charging line, the scooter will be rideable during charge.
stay_on_lockedStay on while lockedboolNone<any string>Disables auto shutdown when the scooter is locked so it stays on forever.
no_overspeed_limitNo overspeed limitboolNone<any string>Removes hard-coded speed limits (and beeping).
bms_uart_76800Change ESC↔BMS baud rate to 76800boolNone<any string>Only if you use the compatible open source BMS!

Please note that all parameters might not be listed.

DRV versions table

Current DRV firmware versions used throughout the production branch.

Ninebot ESx: DRV120 ; DRV133 ; DRV139 ; DRV150 ; DRV151(default)

Ninebot Max: DRV126

Xiaomi 1S: DRV221

Xiaomi Pro 2: DRV223

If the Version spoofing patch is in use, the version number retrieved by apps will be shifted up by 400. This requires no modification to the “version” field so make sure to only use the above values.

Direct power control state table

Case sensitive.

None/“off”: Doesn't change default firmware behavior. For all currently supported firmware versions, the throttle function forces its register value at 0, making DPC inaccessible.

“reg”: Allows switching between DPC and speed-based throttle by writing either 1 or 0 to register 0x76. The register doesn't retain its value after reboot and defaults at 0/off. For the end-user, this would mainly be intended for use within an app such as GM Free.

“dyn”: With this patch, holding the brake lever upon boot (like you'd do for error 15) enables DPC. The regular startup sequence keeps the speed-based throttle.

“on”: DPC is always on.

Output file formats table

Case sensitive.
Defaults to “zip2” if not provided.

“bin”: Barebone final product, binary output. For devs only.

“enc”: Encoded version of the binary. The bare minimum you need to flash a Ninebot scooter, more difficult to use on Xiaomi which has a different encoding rule. Used on Ninebot IAP and Ninebot-Flasher. [missing references about encoding - separate page needed]

“zip”: CamiAlfa's DownG ZIP. Still used by BotoX and many third-party websites, but still does the job for scooters of older generations. Mostly used by Android flashing apps.

“zip2”: An alteration of the original DownG ZIP format containing parameters of the firmware and a broader selection of scooter “dev” variables to choose from. [missing references about zip2 - separate page needed]

Most apps should support both versions of DownG ZIP, but using zip2 is recommended especially on newer scooters to prevent a file from being flashed when it shouldn't - DownG ZIP only having M365 and ES/SNSC as dev variables. It also returns the actual content of the firmware in a human-readable form (params.txt), preventing mistakes from happening.

Both ZIP formats will be delivered with an archive comment consisting of the full request URL, the patcher branch and revision identifiers, as well as a copy of the human-readable parameters. This data is crucial for debugging purposes and must be kept intact!


cfwbuilder.txt · Last modified: 2020/10/23 22:23 by lothean