Adaptive Physical Communication System (APCS)

Installation and First Run

This guide takes you from a clean machine to the app running on a phone, in Chrome, and in the test suite. It covers Windows (the primary development machine for this project), macOS and Linux.

Back to the documentation index.

What you need
Install Flutter
Get the project
Verify the code before touching a phone
Run on an Android phone
Run on an iPhone (macOS only)
Run in Chrome (web)
Windows-specific notes
Project layout at a glance
Next steps

1. What you need

Software

Tool	Version used by the project	Notes
Flutter SDK	3.41.1 (stable)	`flutter --version`
Dart SDK	3.11.0 (bundled with Flutter)	`pubspec.yaml` requires `sdk: ^3.11.0`
Android SDK + platform tools	Recent, via Android Studio	Needed for APKs and `adb`
Java	17	The Android build uses `JavaVersion.VERSION_17`
Xcode	Recent	Only for iOS builds (macOS only)
Google Chrome	Any recent version	For the web build
Git	Any
Python 3 + `imageio-ffmpeg` + Pillow	Optional	Only to regenerate demo media (see Media Pipeline)

Hardware

Two phones for real transfers. Android is the best-tested platform.
A USB cable per phone (or wireless debugging).
Optional: a laptop with a webcam and Chrome can act as a Light or Sound receiver.

2. Install Flutter

Download the Flutter SDK from flutter.dev and unzip it to a path without spaces, e.g. C:\src\flutter.
Add flutter\bin to your PATH.
Run the doctor and fix anything it reports:

flutter doctor -v

Accept the Android licences:

flutter doctor --android-licenses

3. Get the project

git clone https://github.com/harsharaj-s/adaptive-physical-communication-system.git
cd adaptive-physical-communication-system
flutter pub get

Clone into a short path without spaces (for example C:\dev on Windows); see Windows-specific notes.

flutter pub get downloads every package listed in pubspec.yaml: camera, qr, zxing2, record, audioplayers, vibration, sensors_plus, permission_handler, wakelock_plus, image, file_picker, video_player, gal, path_provider, url_launcher and web.

4. Verify the code before touching a phone

flutter analyze     # static analysis — should report "No issues found!"
flutter test        # full test suite — every test should pass

The tests include headless simulations of a phone camera and a room. When they pass, the Light and Sound pipelines work end to end on your machine. See Testing for details.

5. Run on an Android phone

On the phone, enable Developer options: Settings → About phone → tap Build number seven times.
Enable USB debugging in Developer options.
Connect the phone and accept the “Allow USB debugging?” prompt.
Check that Flutter sees it:

flutter devices

Run it:

flutter run                 # debug build, hot reload
flutter run --release       # release build, realistic performance

Use --release for any real transfer test. Debug builds run the QR decoder and the audio DSP far slower, which gives a misleading picture of decode rates.

Installing a pre-built APK instead

If someone gives you app-release.apk:

Copy it to the phone (USB, a cable to a laptop, or any file transfer).
Open it in the phone’s Files app.
Allow “Install unknown apps” for that Files app when Android asks.
Tap Install.

Or, with the phone connected:

adb install -r build\app\outputs\flutter-apk\app-release.apk

Install the same build on both phones. The Light frame format is versioned (APCF v3), and frames from a different version are rejected on purpose.

6. Run on an iPhone (macOS only)

cd ios && pod install && cd ..
open ios/Runner.xcworkspace   # set your Team under Signing & Capabilities
flutter run --release

The first launch asks for camera, microphone, motion and photo permissions as each feature is used. The usage texts are in ios/Runner/Info.plist.

7. Run in Chrome (web)

flutter run -d chrome

Light: the web app can receive by webcam. A canvas sampler reads a 640×640 centre patch.
Sound: send and receive both work, through the laptop’s speaker and microphone.
Vibration: not available (browsers have no vibration receiver).

Chrome asks for camera and microphone permission. Serve over localhost or HTTPS, because browsers block the camera on plain HTTP.

8. Windows-specific notes

Gradle download timeouts. If the first Android build fails with “Connection timed out” while downloading the Gradle distribution, point Gradle at your normal cache:

$env:GRADLE_USER_HOME = "$env:USERPROFILE\.gradle"
flutter build apk --release

Long paths. Keep the project path short. Enable long paths if Git complains: git config --system core.longpaths true.
Antivirus. Real-time scanning of build\ and %USERPROFILE%\.gradle can make Android builds much slower. Consider excluding them.

9. Project layout at a glance

lib/            Dart source (UI, controller, modems, protocol, simulation)
test/           Unit, integration and simulation tests (+ camera and room models)
assets/samples/ Demo photos and narrated explainer videos bundled in the app
tool/           Python media generators and Dart debug scripts
android/ ios/ web/  Platform projects
docs/           This documentation

Full breakdown: Architecture.

10. Next steps

Try a transfer: User Guide.
Prepare a demo: Showcase Guide.
Produce a release APK: Build and Release.

This site is open source. Improve this page.