Update and improve instrument guides across platforms

[mariobehling]

Each PSLab instrument should have a useful guide that helps users understand how to use the instrument, connect the required hardware, and interpret the available options.

Compared to the previous app version, the current Flutter app has several issues with instrument guides:

• Guides are missing for some instruments.
• Some guides were newly implemented but are already out of date.
• Some connection maps are outdated or incomplete.
• Some guide images are low quality and look blurry even without zooming.
• It is not possible to open a guide and pull it all the way to the top of the screen.
• Guides do not consistently explain supported sensors, phone-based usage, or breadboard connections.

The guide system should be reviewed and improved for all instruments.

Current behavior

• Some instruments do not have guides.
• Some existing guides are outdated.
• Some connection maps no longer match the current instrument implementation or hardware support.
• Some guide images are very small, often under 100 KB.
• Some images appear low quality and are difficult to read.
• Guide panels cannot always be expanded fully to the top of the screen.
• Guides do not consistently work or display well across Android, iOS, desktop, and web.
• Guides do not consistently explain whether the instrument requires PSLab hardware, supported sensors, or can use the phone directly.

Expected behavior

Each instrument should provide a current, readable, and useful guide.

The guide should:

• Exist for every instrument.
• Match the current instrument UI and behavior.
• Include up-to-date connection maps where relevant.
• Use higher-quality images where image guides are used.
• Be readable without visible blurriness.
• Work on Android, iOS, desktop, and web where applicable.
• Be expandable so the user can open the guide and pull it all the way to the top.
• Explain how to use the instrument.
• Explain which hardware is supported.
• Explain which sensors are supported.
• Explain whether the phone can be used directly without PSLab hardware.
• Include breadboard connection diagrams where breadboard usage is suitable.

Scope

1. Audit existing guides

• Review all instruments and list which instruments currently have guides.
• Identify instruments with missing guides.
• Identify guides that are outdated.
• Identify outdated or incorrect connection maps.
• Identify guides with low-quality images.
• Identify guides that do not work well on different screen sizes or platforms.
• Compare current guides with the previous app version where useful.

2. Add missing guides

• Add guides for instruments that currently do not have one.
• Ensure each guide contains practical user instructions.
• Ensure each guide explains the instrument purpose.
• Ensure each guide explains required hardware.
• Ensure each guide explains setup and connection steps.
• Ensure each guide explains supported sensors or direct phone usage where applicable.

3. Update outdated guides

• Update guide text to match the current Flutter app UI.
• Update guide text to match current PSLab V5 and PSLab V6 hardware support.
• Update connection maps where they are outdated.
• Remove obsolete information from old guides.
• Ensure terminology is consistent across all guides.

4. Improve guide image quality

• Replace low-quality PNG guide images with sharper versions.
• Use higher-quality PNG files where needed, for example around 120 KB to 250 KB when appropriate.
• Ensure text and connection labels are readable without zooming.
• Ensure images remain reasonably optimized and do not unnecessarily increase app size.
• Use consistent image dimensions, margins, font sizes, and visual style.
• Ensure images render clearly on high-density screens.
• Allow maintainers to add newly created PNGs for the updated guides.

5. Improve guide panel behavior

• Allow the guide panel or guide view to be expanded all the way to the top of the screen.
• Ensure users can scroll through the full guide content.
• Ensure the guide view does not cut off content.
• Ensure opening and closing the guide works reliably.
• Ensure guide layout works in portrait and landscape orientation.
• Ensure guide layout works on Android, iOS, desktop, and web.

6. Add hardware and sensor support information

Each guide should clearly state:

• Whether PSLab V5 is supported.
• Whether PSLab V6 is supported.
• Whether in-built phone sensors can be used.
• Which external sensors are supported.
• Whether the instrument requires hardware connection.
• Whether the instrument can work without PSLab hardware.
• Any platform-specific limitations, for example phone-only sensors or desktop limitations.

7. Add breadboard connection information where relevant

• Add breadboard connection diagrams where breadboard usage is suitable.
• Use a style similar to the previous guide where it was clearer.
• Show correct pin connections.
• Show sensor/module orientation where relevant.
• Include warnings for incorrect wiring where needed.
• Ensure diagrams are readable on mobile screens.

8. Cross-platform support

• Test guide display on Android.
• Test guide display on iOS where available.
• Test guide display on desktop where available.
• Test guide display on web where available.
• Ensure guide assets are bundled correctly for all supported platforms.
• Ensure images load correctly across platforms.

Implementation details

• Review the guide implementation in the current Flutter app.
• Review guide assets and their file sizes.
• Compare existing guides with the previous PSLab app version.
• Create an inventory of instruments and guide status.
• Replace outdated or low-quality PNG assets.
• Add missing guide content.
• Update connection maps.
• Improve the guide view so it can expand to the top of the screen.
• Ensure guide content is scrollable and responsive.
• Add hardware support notes for PSLab V5, PSLab V6, and phone-supported instruments.
• Add or update breadboard connection diagrams where useful.
• Keep image assets optimized, but do not reduce quality so much that labels become unreadable.
• Add tests or documented manual testing steps for guide opening, expansion, scrolling, and platform rendering.

Image asset note

Many current guide images are below 100 KB and the quality is visibly low in some cases. Higher-quality PNGs should be created and added where appropriate.

Suggested target size for new PNG guide images:

• Around 120 KB to 250 KB per image where needed
• Clear enough to read labels without zooming
• Optimized enough to avoid unnecessary app size increase

New guide PNGs can be created separately and added to the repository as part of this work.

Rationale

The instrument guides are important for onboarding users and helping them use PSLab correctly. If guides are missing, outdated, blurry, or incomplete, users may connect hardware incorrectly or fail to understand available app features.

As the app supports more hardware and platforms, guides should clearly explain which instruments work with PSLab V5, PSLab V6, phone sensors, and other supported hardware.

Better guides also reduce confusion for new users, students, workshop participants, and contributors.

Acceptance criteria

• Every instrument has a guide.
• Outdated guides are updated.
• Outdated connection maps are corrected.
• Low-quality guide images are replaced with sharper PNGs where needed.
• Guide images are readable without zooming.
• The guide view can be expanded all the way to the top of the screen.
• Guide content can be scrolled fully.
• Guides work on Android.
• Guides work on iOS where supported.
• Guides work on desktop where supported.
• Guides work on web where supported.
• Each guide states relevant hardware support.
• Each guide states relevant sensor support.
• Each guide states whether phone sensors can be used directly.
• Breadboard connection diagrams are included where suitable.
• Relevant tests or documented manual testing steps are included.