pine64 / bl602-docs Goto Github PK

View Code? Open in Web Editor NEW

65.0 12.0 41.0 44.21 MB

Documentation of the BL602 IC

Home Page: https://pine64.github.io/bl602-docs/

Makefile 29.59% Python 70.41%

bl602 documentation pine64

bl602-docs's Issues

Articles without any content at all should be removed

Several articles are completely empty except for a main header.

This leads to significant bloat in the documentation with titles that do not contain any useful information anyway.

One example is Developer_Environment/openocd/openocd.rst.

These files can be commented out in the index.rst file to remove them from the index, but this will produce the WARNING: document isn't included in any toctree error for each file. Ideally all the files should just be deleted and removed from the index, and any titles requiring body text should be added to an issue.

The full list of empty files is:

Developer_Environment/openocd/openocd.rst
Components/arch.rst
Components/Hal_drv/gpio.rst
Components/Middleware/bloop/bloop.rst
Components/Middleware/blsync/blsync.rst
Components/Middleware/security/security.rst
Components/Network/httpc/httpc.rst
Components/Network/https/https.rst
Components/Network/tls/tls.rst
Components/BLE/provision_WiFi/provision_WiFi.rst
Components/BLE/mesh/mesh.rst

Notice that GPIO has an entry in both Components and Examples. I'm unsure of the difference in content.

Update Linux Starter Guide with 3rd party tool

The Linux Start Guide currently instructs the user to run the BLFlashEnv tool which doesn't exist.
The documentation also states that the IO8 pin should be tied to LOW, while the Pine64 BL602 EVB ver 1.1 board requires IO8 to be tied to HIGH in order to flash.

I intend to replace the current guide with docs on how to build and flash the sdk_app_helloworld example.

Should the guide prefer any specific third party tool? Currently I only got blflash to work since bl602tool requires the creation of the entire image manually, without any documentation for this process.

Shouldn't this repo be called bl602-docs?

The chip is named BL602 (BL standing for Bouffalo Lab, I assume), not BLE602. There is no occurrence of "BLE602" anywhere in the vendor SDK. I assume the confusion came from its similarity to Bluetooth Low Energy.

I know renaming a repo after its been created is suboptimal, but I still think we should do it. It's only 9 hours old, so likely only a few people will have to change their remote URLs, and if we don't change it we'll be stuck with a confusing name forever.

Move hardware notes/manuals into compiled documentation

The Hardware Notes and assorted documentation is currently not available from the compiled docs.
This provides a difficulty of discovery for people using the compiled docs.

I propose either linking to the PDFs and hardware notes, or ideally integrating it into the RST sources.

The Reference Manuals and Data Sheets also come as RST source, so they could also be easily integrated.

Errors/warnings when running `make html`

When building the docs several errors pop up.
Two of the error types are not trivially solvable without input.

The first is that the following image files are missing (image file not readable):

Components/Network/wifi/imgs/image1.png
Developer_Environment/eclipse/imgs/image03.png
Developer_Environment/eclipse/imgs/image06.png
Developer_Environment/freedom_studio/imgs/image06.png
Examples/benchmark_security_aes/imgs/image1.png
Examples/benchmark_security_aes/imgs/image2.png
Examples/benchmark_security_aes/imgs/image3.png
Examples/benchmark_security_aes/imgs/image4.png
Examples/benchmark_security_aes/imgs/image5.png
Examples/demo_audio_udp/imgs/image1.png
Examples/demo_audio_udp/imgs/image2.png
Examples/demo_audio_udp/imgs/image3.png
Examples/demo_cronalarm/imgs/01.png
Examples/demo_storage_romfs/imgs/image3.png

These will either need to be recreated or references removed.

The second is that two files are including files that do not exist.
The including files do not include anything other than the include statement:

src/en/API/sys/cronalarms.rst
src/en/API/wifi/wifi_mgmr.rst

I'll try to look into recreating some of the missing images as well as solving some of the trivially solvable warnings.

Should the files that only include non-existing files be deleted?

Full log (reordered to group related, root is doc repo root):

/src/en/API/sys/cronalarms.rst:4: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: '_build/inc/cronalarms.inc'.
/src/en/API/wifi/wifi_mgmr.rst:4: WARNING: Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: '_build/inc/wifi_mgmr_ext.inc'.

/src/en/Components/Network/wifi/wifi.rst:: WARNING: image file not readable: Components/Network/wifi/imgs/image1.png
/src/en/Developer_Environment/eclipse/eclipse.rst:: WARNING: image file not readable: Developer_Environment/eclipse/imgs/image03.png
/src/en/Developer_Environment/eclipse/eclipse.rst:: WARNING: image file not readable: Developer_Environment/eclipse/imgs/image06.png
/src/en/Developer_Environment/freedom_studio/freedom_studio.rst:: WARNING: image file not readable: Developer_Environment/freedom_studio/imgs/image06.png
/src/en/Examples/benchmark_security_aes/benchmark_security_aes_gcm.rst:: WARNING: image file not readable: Examples/benchmark_security_aes/imgs/image1.png
/src/en/Examples/benchmark_security_aes/benchmark_security_aes_gcm.rst:: WARNING: image file not readable: Examples/benchmark_security_aes/imgs/image2.png
/src/en/Examples/benchmark_security_aes/benchmark_security_aes_gcm.rst:: WARNING: image file not readable: Examples/benchmark_security_aes/imgs/image3.png
/src/en/Examples/benchmark_security_aes/benchmark_security_aes_gcm.rst:: WARNING: image file not readable: Examples/benchmark_security_aes/imgs/image4.png
/src/en/Examples/benchmark_security_aes/benchmark_security_aes_gcm.rst:: WARNING: image file not readable: Examples/benchmark_security_aes/imgs/image5.png
/src/en/Examples/demo_audio_udp/audio_udp.rst:: WARNING: image file not readable: Examples/demo_audio_udp/imgs/image1.png
/src/en/Examples/demo_audio_udp/audio_udp.rst:: WARNING: image file not readable: Examples/demo_audio_udp/imgs/image2.png
/src/en/Examples/demo_audio_udp/audio_udp.rst:: WARNING: image file not readable: Examples/demo_audio_udp/imgs/image3.png
/src/en/Examples/demo_cronalarm/cronalarm.rst:: WARNING: image file not readable: Examples/demo_cronalarm/imgs/01.png
/src/en/Examples/demo_storage_romfs/romfs.rst:: WARNING: image file not readable: Examples/demo_storage_romfs/imgs/image3.png

/src/en/Examples/demo_at/AT.rst:1: WARNING: Title overline too short.
==============
AT Commands Introduction
==============

/src/en/Examples/demo_ble/ble.rst:111: WARNING: Block quote ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:203: WARNING: Block quote ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:257: WARNING: Block quote ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:272: WARNING: Block quote ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:286: WARNING: Block quote ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:352: WARNING: Block quote ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:391: WARNING: Block quote ends without a blank line; unexpected unindent.

/src/en/Examples/demo_ble/ble.rst:107: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:122: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:128: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:154: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:158: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:198: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:253: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:268: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:282: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:347: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:389: WARNING: Bullet list ends without a blank line; unexpected unindent.
/src/en/Examples/demo_ble/ble.rst:407: WARNING: Bullet list ends without a blank line; unexpected unindent.

/src/en/Examples/demo_ble/ble.rst:4: WARNING: duplicate label ble-index, other instance in /src/en/Components/BLE/ble_stack/ble_stack.rst

Improve Flashing Documentation

I have two ideas as to how to improve the flashing documentation.

I could try to interpret the Windows instructions based on the pictures and Google Translate, and write it up in English.
I also saw on the chat a work in progress CLI tool, which I could add to the central documentation as well.
(https://github.com/stschake/bl60x-flash)

Should I do either of these things?

Directory layout is unclear

The layout of the Chinese and English HTML docs seems inconsistent, with the English ones at /html and the Chinese ones at /docs/zh/html. Additionally, having a folder called docs inside a repository explicitly for documentation seems redundant.

Here's my proposal for a directory structure:

sdk: HTML/Sphinx documentation from the original SDK
- zh: Original Chinese
  - source: Sphinx source
  - html: Rendered HTML
- en: English translation
  - source: Sphinx source
  - html: Rendered HTML
mirrored: Files available elsewhere online that we want to preserve, such as BL602_BL604_DS_Datasheet.pdf
reverse_engineered: Docs written by community members, such as my hardware_notes.md
README.md: Top-level docs README describing this directory structure, how to contribute, and related repos.

Thoughts?

Improve front page and initial onboarding documentation

The current Home page (index.rst source, index.html compiled) does not contain any information except for the same listing shown in the sidebar.

The Starter Guides do not mention that UART is used and that UART does not allow for debugging while JTAG does.

The Developer Environment docs do not mention how to connect the JTAG necessary for debugging.

IMO the questions that should be answered by the intro page are:

What is the BL602?

A general short overview of who is making it, what its intended use is and the most important specs.
Information from the wiki can be used here, but less specific.

How does the user set up an environment for developing for the BL602?

Partially answered by the Quick Start guides.
Improvements could be made such as moving the "Connecting to Hardware" portions out of the platform specific documents and better explaining setting up a developer environment and JTAG.

I propose the following structure for the initial onboarding documentation:

Home Page

Short description of BL602 as mentioned above.

Quick Start Guide

Same as the current header.

Preparing and connecting the hardware

Move the current "Connecting the Hardware" sections from Linux and Windows sections out here.

Mention differences in connecting with UART and JTAG.

Setting up a developer environment

Explain Eclipse/Freedom Studio/vscode.
The docs for Eclipse/Freedom Studio are currently very sparse.
vscode is described here.

Compiling

Describe Windows/Linux in separate articles.

Flashing

Again, articles for Windows and Linux.

Debugging

Describe using gdb and vscode as described here and here.

Examples

Gradual introduction and documentation to the different examples.

Translate remaining Chinese articles into English

The following articles still contain Chinese text:

Examples/demo_audio_udp/audio_udp.rst
Examples/demo_cronalarm/cronalarm.rst
Examples/demo_dac/dac.rst
Examples/demo_hbnram/hbnram.rst
Examples/demo_hbnram/hbnram.rst
Examples/demo_storage_psm/psm.rst
Examples/demo_system_cli/cli.rst
Examples/demo_system_fdt/fdt.rst
Examples/demo_zb/zigbee.rst
Examples/sdk_app_easyflash_boottimes/easyflash_boottimes.rst
Examples/sdk_app_pwm/pwm.rst
Examples/benchmark_security_aes/benchmark_security_aes_gcm.rst
Components/Middleware/dts/devicetree.rst
Components/Middleware/log/blog.rst
Components/Middleware/vfs/vfs.rst
Components/Middleware/yloop/yloop.rst
Components/Network/wifi/wifi.rst

Translating any of the above would be an easy way for people to receive an evaluation board, if any are still available.

The following articles contain Chinese but are fixed by currently pending PRs:

Examples/demo_peripherals/uart/ioctl/uart/ioctl.rst
Examples/demo_protocols_http/http.rst

RF info missing from datasheet

The current datasheet is completely missing any kind of data regarding the RF system of the chip.
Actually there is no info regarding TX power (min/max), RX sensitivity, spurious emissions, neighbor channel rejection etc. etc.

Thus it will be very challenging getting CE or FCC certification without further info from Bouffalo.