Differences

This shows you the differences between two versions of the page.

--- zip3 [2022/10/24 23:39] – lothean
+++ zip3 [2024/04/18 21:33] (current) – lothean
@@ Line 1: / Line 1: @@
 ====== ScooterHacking Open-Source Firmware Package (ZIPv3) ======
-Since late 2021, Xiaomi started using GD32 chips on their DRV boards where STM32 chips were previously used. Ninebot soon followed by replacing the STM32 chips by AT32 chips. Some instances of STM32-based BMS boards replacing STM8 ones were also spotted in vehicles of the two aforementionned brands. Those hardware changes didn't happen on the release of a new model - but rather in the middle of the production of existing models; meaning the model in itself was not a good indicator of the hardware inside your vehicle anymore.
+Since late 2021, Xiaomi started using GD32 chips on their DRV boards where STM32 chips were previously used. Ninebot soon followed by replacing the STM32 chips with AT32 chips. Some instances of STM32-based BMS boards replacing STM8 ones were also spotted in vehicles of the two aforementioned brands. Those hardware changes didn't happen on the release of a new model - but rather in the middle of the production of existing models; meaning the model in itself was not a good indicator of the hardware inside your vehicle anymore.
 [[:downg#zip_files|The previous firmware package format/standard]], first introduced a couple of years ago by CamiAlfa's DownG and BotoX's M365 firmware patcher, only used the model to determine whether a firmware was compatible with your current scooter. Given the recent hardware changes, a new firmware package format was needed to bring more granularity over which firmware was compatible with a certain setup, and to provide apps and firmware providers with a way to safely use and produce packages.
-This new package format - nicknamed "ZIPv3" from within the scooter community, since it's the third big alteration of a firmware package inside a ZIP archive - aims to fullfill those new requirements and bring as much future-proofing as possible. The main differences from previous alterations are a list of compatible boards/chips inside the info file, added to the model, and the migration from txt to json.
+This new package format - nicknamed "ZIPv3" from within the scooter community, since it's the third big alteration of a firmware package inside a ZIP archive - aims to fulfill those new requirements and bring as much future-proofing as possible. The main differences from previous alterations are a list of compatible boards/chips inside the info file, added to the model, and the migration from txt to JSON.
-This documentation covers the first released schema version of this format (v3.1). Any documentation to a more recent version will be linker here when available.
+This documentation covers the first released schema version of this format (v3.1). Any documentation to a more recent version will be linked here when available.
-===== \\
+===== Content of a firmware package =====
-Content of a firmware package =====
-All files must be placed to the root of the archive and no other files and folders than those required must be inside the archive.
+All files must be placed at the root of the archive and no other files and folders than those required must be inside the archive.
 ==== info.json ====
-=== Example file ===<code>
+=== Example file ===
+<code>
 {
     "schemaVersion": 1,
@@ Line 36: / Line 37: @@
 }
-</code>===
+</code>
-Details ===
-The //schemaVersion// key located at the root of the json data must contain an integer that matches the schema version used for the current package.\\
+=== Details ===
+The //schemaVersion// key located at the root of the JSON data must contain an integer that matches the schema version used for the current package.\\
 For example, if the integer is 1, then you're using v3.1.
 The //firmware// object contains all of the following data.
-//The displayName// key is pretty self-explanatory. It contains - as a string - the user-friendly name that should be displayed inside when the file is loaded. It's usually used to display the type + version of the loaded file.
+//The displayName// key is pretty self-explanatory. It contains - as a string - the user-friendly name that should be displayed inside an app when the file is loaded. It's usually used to display the type + version of the loaded file.
-The //model// key contains the model this firmware was originally made for, as a string. For a list of in-use values, see the List of models section.
+The //model// key contains the model this firmware was originally made for, as a string. For a list of in-use values, see the [[:zip3#list_of_models|List of models]] section.
-The //enforceModel// key is a boolean that tells the app if in addition to checking for compatible hardware, the current scooter model must match the model of the loaded file. (useful if we don't want the user to change his BLE beacon and thus detected model by flashing a compatible firmware that was made for another model)
+The //enforceModel// key is a boolean that tells the app if, in addition to checking for compatible hardware, the current scooter model must match the model of the loaded file. (useful if we don't want the user to change his BLE beacon and thus detected model by flashing a compatible firmware that was made for another model)
-The //type// key is a string that contains the target internal device the firmware is made for. In-use values are currently **BLE**, **DRV**, and **BMS ** (case senstive).
+The //type// key is a string that contains the target internal device the firmware is made for. In-use values are currently **BLE**, **DRV**, and **BMS ** (case-sensitive).
-The //compatible// object is an array of strings that contains each board compatible with this firmware. For a list of in-use values, see the List of boards section.
+The //compatible// object is an array of strings that contains each board compatible with this firmware. For a list of in-use values, see the [[:zip3#list_of_boards|List of boards]] section.
-The //encryption// key is a string that indicates whether only the **encrypted** firmware file, only the **plain** firmware file or **both** files are contained inside the package. Any other values than the words in bold aren't accepted (case sensitive).
+The //encryption// key is a string that indicates whether only the **encrypted** firmware file, only the **plain** firmware file, or **both** files are contained inside the package. Any other values than the words in bold aren't accepted (case sensitive).
 The //md5// object contains the md5 checksums of the firmware file(s), each inside a string.\\
@@ Line 68: / Line 70: @@
 Only to be included if the //encryption// key inside info.json is set to encrypted or both.
-==== params.txt  ====
+==== params.txt ====
 Optional. Text file containing a summary of patched parameters in the firmware.
@@ Line 79: / Line 81: @@
 Ninebot Max: //max// \\
+Ninebot G2: //g2// \\
+Ninebot G65: //g65// \\
 Ninebot ESx: //esx// \\
 Ninebot E-series: //e// \\
@@ Line 91: / Line 95: @@
 ==== List of boards ====
-Board identifiers are case-sensitive and usually constructed the following way:\\
+Board identifiers are case-sensitive and usually constructed in the following way:\\
 //model_TYPE_PARTICULARITY// \\
-The particularity can be the MCU, a distinguishable sign, the board revision or a combination of all/some of those.\\
+The particularity can be the MCU, a distinguishable sign, the board revision, or a combination of all/some of those.\\
-Some exceptions can apply as some scooters share the same boards, or boards that are deemed compatible enough to be merged together.
+Some exceptions can apply as some scooters share the same boards or boards that are deemed compatible enough to be merged together.
 === List of currently known DRV boards ===
@@ Line 100: / Line 104: @@
 max_DRV_STM32F103CxT6\\
 max_DRV_AT32F415CxT7\\
+g2_DRV_AT32F415CxT7\\
+g65_DRV_AT32F415CxT7\\
 f_DRV_STM32F103CxT6\\
 f_DRV_AT32F415CxT7\\
@@ Line 114: / Line 120: @@
 nb_BLE_ROUND //(ESx & E-series BLE)// \\
 t15_BLE\\
+g2_BLE\\
+g65_BLE\\
 mi_BLE_LEGACY //(4 dots dashboard, M365)// \\
 mi_BLE_NRF51822QFAA //(M365 Pro)// \\
@@ Line 120: / Line 128: @@
 max_BMS_ST8\\
+max_BMS_STM32\\
 esx_e_BMS_ST8\\
-mi_BMS_ST8 (All supported Xiaomi scooters)
+mi_BMS_ST8 //(All supported Xiaomi scooters)//
+===== Using & contributing =====
+Code examples to create & use ZIPv3 firmware packages can be found on our GitHub, [[https://github.com/scooterhacking/fw-zip-package-v3|here]].\\
+You can discuss the standard, propose new ideas, or ask any related questions in the ScooterHacking development group on Telegram, [[https://t.me/scooterhackingassembly|@scooterhackingassembly]]