docs: document the command-line build and adb deploy path

README.md

@@ -10,24 +10,128 @@ not depend on edits made there.
 
 ## Requirements
 
-- Android Studio, with the Android SDK it installs.
-- JDK 17. The Android Gradle Plugin used by this SDK version will not run on an
-  older JDK, and Android Studio's bundled JDK is the simplest way to get it.
-- FIRST Tech Challenge SDK v11.2.1. This is already in the repository; nothing
+Android Studio is not required. The build needs a JDK and some Android SDK
+packages; Android Studio is only one way of obtaining them. The CI build in
+`.github/workflows/build.yml` compiles this project with no Android Studio
+installed anywhere, so the command-line path below is the one that is actually
+tested on every pull request.
+
+- **JDK 17.** This is the version CI builds with, so it is the one known to
+  work. Gradle 9.1.0 and AGP 8.13.2 both predate current JDK releases, and a
+  much newer JDK is not guaranteed to be supported — if the build fails with a
+  class-file or unsupported-version error, check `java -version` first. Do not
+  assume your system default is fine.
+- **Android SDK packages**, listed below. Only three are needed.
+- **FIRST Tech Challenge SDK v11.2.1**, already in this repository. Nothing
   needs to be downloaded separately.
 
-## Build and deploy
+The required SDK packages, and why each one:
 
-Build the team's APK from the repository root:
+| Package | Why |
+| --- | --- |
+| `platforms;android-30` | `build.common.gradle` sets `compileSdkVersion 30` |
+| `build-tools;35.0.0` | the revision AGP 8.13.2 resolves to |
+| `platform-tools` | provides `adb`, used to deploy to the Control Hub |
+
+The NDK is not needed. `build.common.gradle` declares
+`ndkVersion 21.3.6528147`, but neither module has native sources, so it is never
+resolved. Do not spend the download on it.
+
+### Getting the SDK without Android Studio
+
+Download the "command line tools only" package from
+<https://developer.android.com/studio#command-line-tools-only> and unpack it so
+that `sdkmanager` ends up at `$ANDROID_HOME/cmdline-tools/latest/bin`:
+
+```
+export ANDROID_HOME="$HOME/Android/Sdk"
+mkdir -p "$ANDROID_HOME/cmdline-tools"
+unzip commandlinetools-linux-*.zip -d "$ANDROID_HOME/cmdline-tools"
+mv "$ANDROID_HOME/cmdline-tools/cmdline-tools" "$ANDROID_HOME/cmdline-tools/latest"
+export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"
+```
+
+Then accept the licences and install the three packages:
+
+```
+sdkmanager --licenses
+sdkmanager "platform-tools" "platforms;android-30" "build-tools;35.0.0"
+```
+
+Put `ANDROID_HOME` and the `PATH` line in your shell profile so they survive a
+new terminal. Gradle finds the SDK through `ANDROID_HOME`; if you would rather
+not use an environment variable, create a `local.properties` file in the
+repository root containing `sdk.dir=/home/you/Android/Sdk` instead. That file is
+gitignored and must not be committed, because the path is specific to your
+machine.
+
+If you already have Android Studio, you already have all of this. Point
+`ANDROID_HOME` at the SDK it installed, usually `~/Android/Sdk`.
+
+## Build
+
+From the repository root:
 
 ```
 ./gradlew :TeamCode:assembleDebug
 ```
 
-To put that build on the robot, open the project in Android Studio, connect to
-the Control Hub over ADB — either by USB or over wifi to the Control Hub's
-network — and run the `TeamCode` configuration. Android Studio installs the APK
-onto the Control Hub directly.
+The APK is written to
+`TeamCode/build/outputs/apk/debug/TeamCode-debug.apk`.
+
+Every build from this repository is signed with `libs/ftc.debug.keystore`, the
+debug key shipped with the SDK. Keeping that key identical for everyone on the
+team is what lets a new build replace an older one on the Hub in place. A build
+signed with a different key is rejected with a signature mismatch and has to be
+uninstalled first, which is why that one keystore is deliberately still tracked
+in git while `*.jks` and `*.keystore` are otherwise ignored.
+
+## Deploy to the Control Hub
+
+The Control Hub is an Android device and `adb` talks to it directly, so
+deploying does not need an IDE either.
+
+Connect your laptop to the wifi network the Control Hub broadcasts. The default
+name starts with `FTC-` and the default password is `password`; both should have
+been changed already, so ask if you do not know them. On its own network the
+Control Hub is always at `192.168.43.1`, with its web interface on port 8080 and
+adb listening on port 5555.
+
+```
+adb connect 192.168.43.1:5555
+adb devices
+```
+
+`adb devices` should list `192.168.43.1:5555` as `device`. If it says
+`unauthorized` or nothing appears, run `adb kill-server` and connect again.
+Then install the APK and start the Robot Controller:
+
+```
+adb install -r TeamCode/build/outputs/apk/debug/TeamCode-debug.apk
+adb shell am start -n com.qualcomm.ftcrobotcontroller/org.firstinspires.ftc.robotcontroller.internal.PermissionValidatorWrapper
+```
+
+Installing stops the app that was running, and the Hub only autostarts the
+Robot Controller at boot, so it will not come back on its own. The `am start`
+above restarts it; `adb reboot` also works and takes longer.
+
+A one-line version of build-and-deploy, once the connection is up:
+
+```
+./gradlew :TeamCode:assembleDebug && \
+  adb install -r TeamCode/build/outputs/apk/debug/TeamCode-debug.apk && \
+  adb shell am start -n com.qualcomm.ftcrobotcontroller/org.firstinspires.ftc.robotcontroller.internal.PermissionValidatorWrapper
+```
+
+### Using Android Studio instead
+
+Open the project, let it sync, connect to the Control Hub's wifi network, and
+run the `TeamCode` configuration. Android Studio does the same `adb install` and
+launch shown above. If the Hub does not appear in the device dropdown, run
+`adb connect 192.168.43.1:5555` in a terminal first; Android Studio picks up
+devices from the same adb server.
+
+## What is and is not on the deploy path
 
 GitHub is history and review only. Nothing in this repository is on the deploy
 path: pushing a branch, merging a pull request and passing the build check do