User Tools

Site Tools


cfwbuilder

This is an old revision of the document!


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 ProOnline (beta)pro
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.

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

GET parameterDisplay nameTypeDefault valueAccepted valuesDescriptionESxMax1SPro2Pro1
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.
voltageVoltageinteger3636;48Voltage set
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.
p_sportsSports battery currentint(per model)5000→65535Sets battery current limit for all Sports modes.
p_driveDrive battery currentint(per model)5000→65535Sets battery current limit for all Drive modes.
p_ecoEco battery currentint(per model)5000→65535Sets battery current limit for Eco mode.
i_sportsSports phase currentint(per model)10000→65535Sets phase current limit for Sport mode
i_driveDrive phase currentint(per model)10000→65535Sets phase current limit for Drive 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.
current_raising_coefficientCurrent raising coefficientint3000→16000How fast current will be applied. Affecting throttle speed up rate.
no_kersNo KERSboolNone<any string>Disables energy recovery when the throttle is inactive. Clonk-free.
kers_min_sppedMinimum speed for engaging KERSint60→65Sets minimum threshold for KERS activation
wheel_speed_constWheel Speed Multiplierint8“:390; 10”: 315200→500Don't change if you use stock tires
wheel_sizeWheel size in inchesint8.50→30Wheel size in inches, default 8.5“, don't change if you use stock tires
error_raising_levelError raising levelint00→3https://wiki.scooterhacking.org/doku.php?id=nberrorcodes
brake_limitLever virtual limitint1100→130Sets brake lever virtual limit
brake_i_minMinimum phase currentint80001000→55000Sets minimum phase current
brake_i_maxMaximum phase currentint300001000→55000Sets maximum phase current
brake_current_raising_coefficientBrake current raising coefficientint5000→16000How fast current will be applied. Affecting brake speed up rate
brake_min_speedMinimum speed for applying brakeint30→255Minimum speed at which electronic brake can be applied
no_brake_light_flashStatic brake lightboolNone<any string>Enforces German brake light behavior for other regions.
brake_light_modeBrake light behaviorstringdefaultdefault;static
;reversed;strobe
Sets brake light behavior
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!
m365_compatPro1 FW on classic BLEstringoffon;offChanges dashboard message type from “Pro” to “Regular” (for 4-dot M365 dashboard only!).

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!

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 1: DRV155

Xiaomi Pro 2: DRV223 (default), DRV224

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.1614534312.txt.gz · Last modified: 2022/01/15 01:33 (external edit)