Merge pull request #336 from tadeubas/docs-update

Small docs changes
selfcustody · Mar 20, 2024 · 8431fdf · 8431fdf
2 parents acf5f1c + a877f7f
commit 8431fdf
Show file tree

Hide file tree

Showing 9 changed files with 36 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -63,8 +63,8 @@ fatal: clone of ... failed
 Failed to clone ...
 ```
 
-## Install krux and dev tools
-The krux code is a Python package that should be installed with [Poetry](https://python-poetry.org/). To generate a new `poetry.lock` file use: `poetry lock --no-update`.
+## Install Krux and dev tools
+The Krux code is a Python package that should be installed with [Poetry](https://python-poetry.org/). To generate a new `poetry.lock` file use: `poetry lock --no-update`.
 ```bash
 pip install poetry
 poetry install
@@ -117,7 +117,7 @@ Type "help", "copyright", "credits" or "license" for more information.
 ```
 
 ## Run the simulator
-This can be useful for testing a change to the krux code without having to run a full build and flash, visual regression testing,
+This can be useful for testing a change to Krux code without having to run a full build and flash, visual regression testing,
 generating screenshots, or even just trying out Krux before purchasing a device. However, the simulator may not behave exactly as
 the HW device and may not have all features implemented (e.g. scanning via camera a TinySeed currently only works on the HW device)
 
@@ -287,7 +287,7 @@ poetry run python i18n.py validate
 # Format translation files properly:
 poetry run python i18n.py prettify
 
-# Create the compiled table for krux translations.py
+# Create the compiled table for Krux translations.py
 poetry run python i18n.py bake
 ```
 
@@ -317,7 +317,7 @@ To create or edit translations on documentation (TODO: need help!), read more [h
 Once changes are made, you can run:
 
 ```bash
-poetry run mkdocs serve
+poetry run poe docs
 ```
 
 # Inspired by these similar projects

diff --git a/docs/faq.en.md b/docs/faq.en.md
@@ -3,6 +3,13 @@ Some Amigo screens have inverted X coordinates while others don’t. If you noti
 
 Others have found that there are issues with the colors displayed in the interface and camera preview. To fix this we have two options in `Settings > Hardware > Display`, `BGR Colors` and `Inverted Colors`, test with them until the colors appear to be correct on your device.
 
+## Why doesn't my Maix Amigo touchscreen work with v24.03.0 if it worked fine with v23.09.1?
+<img src="../img/amigo-inside-switch-up.jpg" align="right">
+
+We added IRQ to the firmware, so when you open your Maix Amigo, you will see a switch in the middle of the device board, it must be in the upper position for the touchscreen to work with v24.03.0 and later.
+
+<div style="clear: both"></div>
+
 ## Why isn't my device charging or being recognized when connected to the computer's USB?
 If you have a Maix Amigo, make sure you're using the USB-C port at the bottom of the device, not the one on the left side.
 
@@ -41,7 +48,7 @@ sudo apt-get remove brltty
 Check if the downloaded file matches the device, this can also occur due to data corruption. Try downloading binaries again. You can install [MaixPy IDE](https://dl.sipeed.com/shareURL/MAIX/MaixPy/ide/v0.2.5) to help with debugging, Tools > Open Terminal > New Terminal > Connect to serial port > Select a COM port available (if it doesn't work, try another COM port). It will show the terminal and some messages, a message about an empty device or with corrupted firmware appears like: "interesting, something's wrong, boot failed with exit code 233, go to find your vendor."
 
 ## What are all the features available? What are the additional features of the Test (Beta) version? Is there an Android app?
-For [official releases](https://github.com/selfcustody/krux/releases) you will find all the features detailed here on the [Getting Started page](getting-started/index.md) with a brief summary on the [Navigation Overview page](getting-started/navigation.md). The latest and most experimental features, which we sometimes share on our social media, can be found only in the [test (beta) repository](https://github.com/odudex/krux_binaries/). Only official releases are signed, Test (Beta) is just for trying new things and providing feedback. Krux Android app ia available as an `apk` on the [test (beta) repository](https://github.com/odudex/krux_binaries/).
+For [official releases](https://github.com/selfcustody/krux/releases) you will find all the features detailed here on the [Getting Started page](getting-started/index.md) with a brief summary on the [Navigation Overview page](getting-started/navigation.md). The latest and most experimental features, which we sometimes share on our social media, can be found only in the [test (beta) repository](https://github.com/odudex/krux_binaries/). Only official releases are signed, Test (Beta) is just for trying new things and providing feedback. Krux Android app is available as an `apk` on the [test (beta) repository](https://github.com/odudex/krux_binaries/) (requires Android 6.0 or above).
 
 ## Why does Krux show an xpub for a segwit address?
 The xpub that Krux displays follows the [bitcoin core descriptors spec](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md/#key-origin-identification) and includes key origin and derivation info that, in theory, makes zpubs (and ypubs) unnecessary *if the wallet software being shown this extra information can parse it*. 

diff --git a/docs/getting-started/index.en.md b/docs/getting-started/index.en.md
@@ -1,3 +1,5 @@
+<img src="../img/krux-devices.jpg">
+
 Krux is open-source Bitcoin signing firmware for devices with the K210 chipset.
 
 Signing operations in Krux are done offline via QR code or via SD card. You can create/load your BIP-39 mnemonic, or import a wallet output descriptor, and sign transactions all without having to plug the device into your computer (except to initially install the firmware). It reads QR codes with its camera and outputs QR codes to its screen, or to paper via an optional [thermal printer attachment](../getting-started/features/printing.md). 

diff --git a/docs/getting-started/installing/from-gui.en.md b/docs/getting-started/installing/from-gui.en.md
@@ -2,7 +2,7 @@ This page explains how to install Krux with KruxInstaller (GUI).
 
 ### Installing from a GUI
 
-You can install krux onto your K210-based device using our official desktop application, which we named [KruxInstaller](https://github.com/selfcustody/krux-installer), available for Linux and Windows.
+You can install Krux onto your K210-based device using our official desktop application, which we named [KruxInstaller](https://github.com/selfcustody/krux-installer), available for Linux and Windows.
 
 Under the hood the GUI uses the same methods described in [Installing from pre-build release](../installing/from-pre-built-release.md), i.e. download, verify and flash the latest official release, but you won't need to type any command. Additionally you will be able to install the [pre-built test (beta) release](../installing/from-test-release.md) too.
 
@@ -48,7 +48,7 @@ chown +x ./KruxInstaller-0.0.1-alpha-4.AppImage
 If you use Windows, the first time you run the `.exe` file the system will ask you if you trust the application. Click on `more info` and then `Run anyway`.
 
 ### Openssl
-When downloading the official krux firmware, it is necessary to verify the signature to confirm the authenticity of the binaries using OpenSSL tool.
+When downloading the official Krux firmware, it is necessary to verify the signature to confirm the authenticity of the binaries using OpenSSL tool.
 
 On Linux, verification is easily done since OpenSSL is already installed. On windows we would need to install it first. To avoid that, we packaged a stable version of OpenSSL, compiled from source. The compilation process is done entirely in a virtual environment on github and it is expected to be fully verifiable and free of malicious code. You can check the build steps in [github actions](https://github.com/selfcustody/krux-installer/actions).
 

diff --git a/docs/getting-started/usage/generating-a-mnemonic.en.md b/docs/getting-started/usage/generating-a-mnemonic.en.md
@@ -91,8 +91,8 @@ Note: For 12-word mnemonics, only the first half of the SHA256 hash is used (128
 
 ### How to verify
 
-Don't trust, verify.  We encourage you not to trust any claim you cannot verify yourself. Therefore, there are wallets that use compatible algorithms to calculate the entropy derived from dice rolls. You can use the [SeedSigner](https://seedsigner.com/) or Coldcard hardware wallets, or even the [Bitcoiner Guide website](https://bitcoiner.guide/seed/), they share the same logic that Krux uses and will give the same mnemonic.
+Don't trust, verify.  We encourage you not to trust any claim you cannot verify yourself. Therefore, there are wallets that use compatible algorithms to calculate the entropy derived from dice rolls. You can use the [SeedSigner](https://seedsigner.com/) or Coldcard hardware wallets, or even the [Bitcoiner Guide website](https://bitcoiner.guide/seed/), they share the same logic that Krux uses and will give the same mnemonic for the dice roll method.
 
 ## Alternatives
 
-You can use any other offline airgapped devices to generate your mnemonic. If you want to use a regular PC, a common strategy is to boot the PC using [Tails](https://tails.boum.org/) from a USB stick, without connecting the device to the internet, and then use a copy of the the [Bitcoiner Guide website](https://bitcoiner.guide/seed/) or even [Ian Coleman's BIP-39 Tool](https://iancoleman.io/bip39/). It's worth noting that both generate a QR code that Krux can read via the QR input method mentioned on the next page (Loading a Mnemonic).
+You can use any other offline airgapped devices to generate your mnemonic. If you have an old Android smartphone that is offline (airplane mode [no active CDMA or GSM chip], no Wifi connection, no Bluetooth and localization service turned off), you can use the [Krux app for Android](../../faq.md#what-are-all-the-features-available-what-are-the-additional-features-of-the-test-beta-version-is-there-an-android-app). If you want to use a regular PC, a common strategy is to boot the PC using [Tails](https://tails.boum.org/) from a USB stick, without connecting the device to the internet, and then you can run Krux using our [simulator](https://github.com/selfcustody/krux?tab=readme-ov-file#run-the-simulator), use a copy of the the [Bitcoiner Guide website](https://bitcoiner.guide/seed/) or even [Ian Coleman's BIP-39 Tool](https://iancoleman.io/bip39/). It's worth noting that both generate a QR code that Krux can read via the QR input method mentioned on the next page (Loading a Mnemonic).
diff --git a/docs/img/amigo-inside-switch-up.jpg b/docs/img/amigo-inside-switch-up.jpg
diff --git a/docs/img/krux-devices.jpg b/docs/img/krux-devices.jpg
diff --git a/docs/parts.en.md b/docs/parts.en.md
@@ -1,11 +1,14 @@
-**Krux compatible devices comparative table**
+## Krux Compatible Devices
+<img src="../img/krux-devices.jpg">
+
+### Comparative Table
 
 | Device | M5stickV | Maix Amigo | Maix Dock | Maix Bit | Yahboom k210 module |
 | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
 | Price avg. | US$50 | US$55 | US$35 | US$35 | US$60 |
 | Screen size / resolution | 1.14" / 135*240 | 3.5" / 320*480 | 2.4" / 240*320 | 2.4" / 240*320 | 2" / 240*320 |
 | Touchscreen  | :x: | Capacitive | :x: | :x: | Capacitive |
-| Camera  | OV7740 | OV7740 rear<br>GC0328 front | GC0328 | OV2640 or<br>OV5642 | OV2640 |
+| Camera  | OV7740 | OV7740 rear<br>GC0328 front | GC0328 | OV2640 or<br>OV5642 | OV2640 <!-- or<br>GC2145 --> |
 | Battery  | 200mAh | 520mAh | :x: | :x: | :x: |
 | Requirements | None | None | [Rotary encoder](https://duckduckgo.com/?q=ky-040)<br> [3D printed case](https://github.com/selfcustody/DockEncoderCase)<br> Soldering<br>Assembly | Buttons<br> [3D printed case](https://github.com/selfcustody/MaixBitCase)<br> Soldering<br>Assembly | None |
 | Warnings  | [:material-information:{ title="M5stickV and USB-C" }](#m5stickv-info) | [:material-information:{ title="Maix Amigo screens" }](#amigo-info) | [:material-information:{ title="Maix Dock and soldered pin" }](#dock-info) | Camera has<br> lens distortion | Micro USB |
@@ -28,8 +31,9 @@ Some stores ship the Maix Dock with soldered pin connectors that do not fit into
 28nm process, dual-core RISC-V 64bit @400MHz, 8 MB high-speed SRAM, DVP camera and MCU LCD interface, AES Accelerator, SHA256 Accelerator, FFT Accelerator.
 </i>
 
-## Devices
 ### M5StickV
+<img srcset="../img/maixpy_m5stickv/logo-125.png" align="right">
+
 Available from many distributors, including:
 
 - [M5Stack](https://shop.m5stack.com/products/stickv)
@@ -40,7 +44,11 @@ Available from many distributors, including:
 - [Cytron](https://www.cytron.io/c-development-tools/c-fpga/p-m5stickv-k210-ai-camera-without-wifi)
 - [OKDO](https://www.okdo.com/p/m5stickv-k210-ai-camera-without-wifi/)
 
+<div style="clear: both"></div>
+
 ### Maix Amigo
+<img srcset="../img/maixpy_amigo/logo-150.png" align="right">
+
 Available from many distributors, including:
 
 - [Seeed Studio](https://www.seeedstudio.com/Sipeed-Maix-Amigo-p-4689.html)
@@ -50,6 +58,8 @@ Available from many distributors, including:
 - [AliExpress](https://www.aliexpress.com/w/wholesale-sipeed-amigo.html)
 - [Amazon](https://www.amazon.com/s?k=sipeed+amigo&dc)
 
+<div style="clear: both"></div>
+
 ### Maix Dock and Maix Bit
 For the DIYers, the Maix Dock and Maix Bit are also supported but will require sourcing the parts individually and building the device yourself.
 
@@ -58,7 +68,7 @@ Below are example implementations with instructions on how to recreate them:
 - [https://github.com/selfcustody/DockEncoderCase](https://github.com/selfcustody/DockEncoderCase)
 - [https://github.com/selfcustody/MaixBitCase](https://github.com/selfcustody/MaixBitCase)
 
-## Ohter parts
+## Other Parts
 ### USB-C Charge Cable
 This will be included with the M5StickV and Maix Amigo that you purchase from one of the distributors above. It will be necessary to power and charge the device and to initially flash the firmware.
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -78,3 +78,6 @@ test-verbose = "poetry run pytest --cache-clear --cov src/krux --cov-report html
 
 # pre commit (do formatting, linting and tests)
 pre-commit = ["format", "lint", "test"]
+
+# run docs locally
+docs = "poetry run mkdocs serve"