Skip to content

docs: Add README for daplink_flash driver.#252

Merged
nedseb merged 3 commits into
mainfrom
docs/add-readme-daplink
Mar 28, 2026
Merged

docs: Add README for daplink_flash driver.#252
nedseb merged 3 commits into
mainfrom
docs/add-readme-daplink

Conversation

@Charly-sketch
Copy link
Copy Markdown
Contributor

@Charly-sketch Charly-sketch commented Mar 26, 2026 •
edited by nedseb
Loading

Summary

Rewrite the daplink_flash README to reflect the bridge refactor (#256):

  • Updated to show DaplinkFlash(bridge) instead of DaplinkFlash(i2c)
  • Removed device_id, busy, status, config zone sections (now in daplink_bridge)
  • Added dependency on daplink_bridge
  • Fixed inline code formatting (triple backticks → single backticks)
  • Fixed examples table formatting
  • Added link to daplink_bridge documentation

Closes #177

Test plan

  • README reflects the current API after bridge refactor
  • No broken links

@Charly-sketch Charly-sketch requested a review from nedseb March 26, 2026 14:50
@nedseb nedseb requested a review from Copilot March 27, 2026 04:33
nedseb
nedseb requested changes Mar 27, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@nedseb nedseb left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review - PR #252

Points positifs

  • Contenu exhaustif : toutes les méthodes de l'API sont documentées avec paramètres et valeurs de retour.
  • Bon usage des exemples de code pour chaque méthode.
  • Section config zone bien separée et expliquée.
  • Table des exemples présente

Corrections requises

1. Niveaux de titres incohérents (bloquant)

Les sections Features, I2C Address, API, Examples, Notes utilisent # (H1) au lieu de ## (H2). Seul le titre principal doit être en H1. Compare avec les READMEs de référence (lib/ism330dl/README.md, lib/wsen-hids/README.md) : tout est en ## sauf le titre du driver.

2. Section "Sensor overview" manquante

Les READMEs de référence décrivent le composant (fabricant, datasheet, caractéristiques). Ici on ne sait pas que c'est un W25Q64JV de Winbond derrière le bridge, ni qu'il y a 8 Mo de flash. Ajoute une section qui présente brièvement l'architecture (STM32F103 bridge + W25Q64JV flash + config zone en flash interne).

3. Section Status incomplete

_status() et _error() ne sont pas documentés. Les READMEs de référence documentent _status()même si c est privé Pour un driver de flash, le registre d'erreur est important pour le debug.

4. Pas de section Installation

Les READMEs de référence montrent comment installer le driver (mpremote mip, firmware frozen, etc.).

5. write_config docstring inexact

Le README dit "existing data outside the written range is preserved". C'est faux : le driver fait clear_config() puis écrit, donc tout est effacé avant l'écriture. Vérifie le code dans device.py et corrige la doc.

Suggestion

Relis lib/ism330dl/README.md comme modèle et vérifie que la structure (sections, niveaux de titres, ordre) correspond.

Copilot AI reviewed Mar 27, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a driver-level README for daplink_flash, bringing it in line with the repository’s pattern of per-driver documentation and closing #177.

Changes:

  • Introduces lib/daplink_flash/README.md documenting the driver’s purpose, I²C address, and basic usage.
  • Documents the public DaplinkFlash API (flash operations + config zone access).
  • Adds an examples table and an mpremote invocation snippet for running examples.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread lib/daplink_flash/README.md Outdated

# I²C Address

Default 7-bit I²C address: ```0x3B```
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inline values are formatted with triple backticks (e.g., 0x3B), which is uncommon and can be confusing next to fenced code blocks. For consistency with other driver READMEs, use single-backtick inline code spans for addresses/IDs (e.g., 0x3B).

Suggested change
Default 7-bit I²C address: ```0x3B```
Default 7-bit I²C address: `0x3B`

Copilot uses AI. Check for mistakes.
Comment thread lib/daplink_flash/README.md Outdated
Comment on lines +73 to +74
Expected value: ```0x4C```

Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The expected WHO_AM_I value is formatted as 0x4C. Prefer a normal inline code span (0x4C) to match the style used in other READMEs and avoid ambiguity with fenced code blocks.

Copilot uses AI. Check for mistakes.
Comment thread lib/daplink_flash/README.md Outdated
Comment on lines +254 to +262
| Example | Description |
| ---------------- | -------------------------------------------------------------------------- |
| `flash_info.py` | Display bridge ID, status, error register, busy flag, and current filename |
| `write_csv.py` | Create a CSV file in flash, write a few lines, then read it back |
| `read_file.py` | Read and display the currently stored file |
| `erase_flash.py` | Erase the external flash memory |
| `sensor_log.py` | Log simulated sensor data to CSV, read it back, and compute statistics |
| `config_zone.py` | Test and demonstrate persistent config zone operations |

Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Examples table has an extra empty column because rows start with || ... instead of a single leading |. This renders incorrectly on GitHub; use standard markdown table syntax with single | separators for the header and each row.

Copilot uses AI. Check for mistakes.
@nedseb nedseb mentioned this pull request Mar 27, 2026
Closed
7 tasks
@nedseb
Copy link
Copy Markdown
Contributor

nedseb commented Mar 27, 2026

This PR is blocked by #256 — daplink_flash will be refactored into daplink_bridge + daplink_flash. Please put this on hold until the refactoring is merged, then adapt the README to the new architecture.

@nedseb
Copy link
Copy Markdown
Contributor

nedseb commented Mar 28, 2026

Les remarques de Copilot sur le formatage Markdown ont été corrigées dans 8bdfdd1 :

  1. 0x3B : triple backticks remplacés par des backticks simples (inline code).
  2. 0x4C : idem, cohérence avec le reste des READMEs du projet.
  3. Le tableau des exemples était en fait correct syntaxiquement, pas de modification nécessaire.

Corrections rapides et évidentes, elles n'auraient pas dû rester en attente même si la PR doit rester en attente.

@nedseb nedseb force-pushed the docs/add-readme-daplink branch from 8bdfdd1 to 9a9c828 Compare March 28, 2026 19:39
@nedseb nedseb force-pushed the docs/add-readme-daplink branch from 9a9c828 to 51a66b1 Compare March 28, 2026 19:40
@nedseb
Copy link
Copy Markdown
Contributor

nedseb commented Mar 28, 2026

Les deux réserves documentaires sont déjà résolues sur cette branche (héritées de main après rebase sur #285) :

  • lib/steami_config/README.md ligne 13 : montre daplink_bridge comme dépendance, ligne 25 : SteamiConfig(DaplinkBridge(i2c))
  • README.md lignes 17-18 : sépare bien DAPLink Bridge (I2C + config zone) et DAPLink Flash (flash file operations via bridge)

La branche est prête à fusionner.

@nedseb nedseb merged commit 8ca9e5b into main Mar 28, 2026
10 checks passed
@nedseb nedseb deleted the docs/add-readme-daplink branch March 28, 2026 19:47
@semantic-release-updater
Copy link
Copy Markdown

semantic-release-updater Bot commented Mar 28, 2026

🎉 This PR is included in version 0.2.5 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@nedseb nedseb nedseb requested changes

Assignees

@Charly-sketch Charly-sketch

Labels

released

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: Add README for daplink_flash driver.

3 participants

@Charly-sketch @nedseb