From adf92d8d79f5d26aa20b9f460015d88593b3f60e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Laignel?= <fengalin@free.fr>
Date: Wed, 11 Jan 2023 22:59:23 +0100
Subject: [PATCH] README: add a Troubleshooting section

... and add README to the packages.
---
 .github/workflows/package.yml |  3 ++
 README.md                     | 55 ++++++++++++++++++++++++++++++-----
 2 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
index 299f0c8..46e722d 100644
--- a/.github/workflows/package.yml
+++ b/.github/workflows/package.yml
@@ -53,6 +53,7 @@ jobs:
       run: |
         mkdir -p temp/${{ env.app_variant }}
         cp target/release/${APP_NAME} temp/${{ env.app_variant }}/
+        cp README.md temp/${{ env.app_variant }}/
         cp res/org.fengalin.${APP_NAME}.desktop temp/${{ env.app_variant }}/
         cargo-about generate -o temp/${{ env.app_variant }}/LICENSES.html about.hbs
         mkdir -p packages
@@ -120,6 +121,7 @@ jobs:
     - name: Package
       run: |
         mkdir -p temp/${{ env.app_variant }}
+        cp README.md temp/${{ env.app_variant }}/
         cargo-about generate -o temp/${{ env.app_variant }}/LICENSES.html about.hbs
         lipo target/release/${APP_NAME} target/aarch64-apple-darwin/release/${APP_NAME} -output temp/${{ env.app_variant }}/${APP_NAME} -create
         mkdir -p packages
@@ -175,6 +177,7 @@ jobs:
     - name: Package
       run: |
         mkdir "temp\${{ env.app_variant }}"
+        Copy-Item README.md "temp\${{ env.app_variant }}\"
         Copy-Item "target\release\${{ env.app_name }}.exe" "temp\${{ env.app_variant }}\"
         cargo-about generate -o "temp\${{ env.app_variant }}\LICENSES.html" about.hbs
         mkdir packages
diff --git a/README.md b/README.md
index 2c48050..2e63399 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,9 @@
 
 `jstation-controller` is a cross-platform interface to control the J-Station guitar and bass modeling and effect processing system.
 
-Pre-built packages are available from the [release page](https://github.com/fengalin/jstation-controller/releases). See below for build instructions.
+Pre-built packages are available for Linux, macOS and Windows from the
+[release page](https://github.com/fengalin/jstation-controller/releases).
+See the dedicated chapter below if you want to build the application from source.
 
 ![jstation-controller UI](assets/screenshot_20230110.png "jstation-controller UI")
 
@@ -20,29 +22,68 @@ Pre-built packages are available from the [release page](https://github.com/feng
 - [ ] Import a Program bank from a file.
 - [ ] Export a Program bank to a file.
 
-## Dependencies
+## Troubleshooting
+
+### Could not connect to J-Station
+
+There are many reasons for not being able to connect to J-Station.
+This could range from a simple physical connection to conflicts
+with other MIDI devices.
+
+#### Check the connection
+
+1. Make sure the MIDI OUT link from the computer is connected to
+the MIDI IN port on the J-Station and vice versa.
+2. Make sure the MIDI/J8 switch of the J-Station is switched to
+the right when looking at the back of the J-Station. The switch must
+be vertically aligned with the top mark next to the MIDI IN label.
+
+#### Check that the MIDI interface is detected
+
+##### The main window shows up
+
+The MIDI ports detected should show up in the MIDI Connection picklists.
+If the picklists are empty, you probably have an issue with your MIDI interface.
+Check if you need to install drivers and if thee are properly installed.
+
+If you can see the MIDI ports in the picklists but the connection fails when
+you try to auto-connect:
+
+- Disconnect any other MIDI device
+- Follow the J-Station User's Guide and change the MIDI channel (see Section 5 -
+Other Functions, p. 29 of the english version).
+
+## Build from Source
+
+Prebuilt packages are available for Linux, macOS and Windows from the
+[Release page](https://github.com/fengalin/jstation-controller/releases).
+
+The following chapters are only intended for users who want to build the
+application from source.
+
+### Dependencies
 
 This application uses the following crates which require system level libraries:
 
 - [`iced`](https://crates.io/crates/iced).
 - [`midir`](https://crates.io/crates/midir).
 
-### Linux
+#### Linux
 
 Minimum dependencies include development libraries for:
 
 - Wayland (`libwayland-client`, `libwayland-dev`, ...) or X11 (`libxkbcommon-dev`, ...)
 - alsa (`alsa-lib-devel`, `libasound2-dev`, ...)
 
-### macOS
+#### macOS
 
 If you can test the application on this OS, please open a PR with instructions.
 
-### Windows
+#### Windows
 
 If you can test the application on this OS, please open a PR with instructions.
 
-## Build
+### Build
 
 You need a stable Rust toolchain for the target host. Get it from [this page](https://www.rust-lang.org/fr/tools/install).
 On a Unix-like system, you should be able to install `rustup` from your packet
@@ -55,7 +96,7 @@ Clone the git tree and run the following command in an environment where
 cargo b --release
 ```
 
-## Run
+### Run
 
 After a successful compilation, launch the executable with: