diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 000000000..7f1dcf178 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,412 @@ +# One-click release of the Java API: GitHub Packages, a GitHub Release, and the MATLAB jar. +# +# How to release +# 0. On the bench, at the commit to release: tools/hil/run-java-hil.ps1 -Report (tools/hil/README.md). +# It posts the commit status "java-hil"; the build job stops unless that passed, or hil_waiver +# gives a Jira key (the waiver goes into the release notes). Dry runs only warn. +# 1. Actions -> "Release Java API" -> Run workflow (on master). Leave `version` blank for the next +# patch after the last API_v release (0.11.8_beta -> 0.11.9_beta), or type one. +# 2. Review and merge the ShimmerJavaClass.jar PR it opens in Shimmer-MATLAB-ID. +# 3. Run "Release Android API" in ShimmerAndroidAPI, which builds against this version by default. +# +# The version is not kept in the source. The build files read it from -PreleaseVersion, which this +# workflow passes, and say 'local' otherwise; the API_v tags record what was released. +# +# One run does, in order, and creates nothing public until the build and tests have passed: +# build picks the version; fails if API_v is already tagged; tests ShimmerDriver and builds +# ShimmerDriverPC exactly as gradle.yml does. Read-only: it runs on PRs too. +# publish real releases only, and the only job with packages:write. Publishes shimmerdriver, +# shimmerbluetoothmanager and shimmerdriverpc together with one `gradlew publish` +# (DEV-1115: publishing them one at a time by hand left shimmerbluetoothmanager +# 0.11.8_beta unpublished), and keeps the jars it published for the release +# matlab-jar builds ShimmerJavaClass.jar as Java 8 bytecode (`shadowJar -PmatlabJava8`), on a +# separate runner so its Java 8 classes cannot end up in the published jars +# release tags API_v on the commit it built and creates the GitHub Release, with +# notes from the previous API_v release and the jars attached. It is not marked +# "Latest", which stays with the Consensys releases in this repo. +# update-matlab opens a PR in Shimmer-MATLAB-ID replacing libs/ShimmerJavaClass.jar. Needs the +# MATLAB_REPO_TOKEN secret: a fine-grained token for ShimmerResearch/Shimmer-MATLAB-ID +# with Contents and Pull requests read/write. +# +# A failed job can be re-run on its own with "Re-run failed jobs"; the jobs before it are not +# repeated. A failed publish can leave some of the three versions in GitHub Packages: delete those +# versions under the repo's Packages before re-running, or bump the version. +# +# dry_run runs build and matlab-jar without publishing, from any branch; a blank version still picks +# the next one, so the run shows what a real release would be called. The workflow also +# dry-runs on any PR that changes this file. + +name: Release Java API + +on: + workflow_dispatch: + inputs: + version: + description: 'Version, e.g. 0.12.0_beta. Blank = next patch after the last release' + type: string + required: false + dry_run: + description: 'Build and test only; publish nothing' + type: boolean + default: false + hil_waiver: + description: 'Jira key to release without a passing hardware test (HIL), e.g. DEV-1234. Blank = require one' + type: string + required: false + pull_request: + paths: + - '.github/workflows/release.yml' + +concurrency: + group: release-java-api + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + timeout-minutes: 30 # a hung Gradle daemon otherwise holds the runner for 6 hours + # Read-only on purpose: this job also runs on PRs, and any code in a job can recover that + # job's token. Only the publish job, which runs on real releases alone, can write packages. + permissions: + contents: read + statuses: read # the hardware test result the bench posts on the commit + env: + DRY_RUN: ${{ github.event_name != 'workflow_dispatch' || inputs.dry_run }} + outputs: + version: ${{ steps.version.outputs.version }} + tag: ${{ steps.version.outputs.tag }} + previous_tag: ${{ steps.version.outputs.previous_tag }} + hil: ${{ steps.hil.outputs.hil }} + steps: + - name: Release from master only + if: env.DRY_RUN != 'true' && github.ref != 'refs/heads/master' + run: | + echo "::error::A release must run on master, not ${GITHUB_REF_NAME}. Tick dry_run to try another branch." + exit 1 + + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + with: + fetch-depth: 0 # tags, to refuse a version that is already released + # Keep the token out of .git/config, where the Gradle build (and any plugin or dependency + # it runs) could read it. Nothing here needs git credentials after checkout; gh uses GH_TOKEN. + persist-credentials: false + + - name: Choose the version + id: version + env: + GH_TOKEN: ${{ github.token }} + REQUESTED: ${{ inputs.version }} + run: | + PREVIOUS_TAG=$(gh release list --repo "$GITHUB_REPOSITORY" --limit 200 --json tagName,createdAt \ + --jq '[.[] | select(.tagName | startswith("API_v"))] | sort_by(.createdAt) | last | .tagName // ""') + if [ -n "$REQUESTED" ]; then + VERSION=$REQUESTED + else + # Next patch after the last release, keeping its suffix: 0.11.8_beta -> 0.11.9_beta. + last=${PREVIOUS_TAG#API_v} + if ! [[ "$last" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)(.*)$ ]]; then + echo "::error::Cannot work out the next version from '${PREVIOUS_TAG:-no previous release}'. Type one in the version box." + exit 1 + fi + VERSION="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.$((BASH_REMATCH[3] + 1))${BASH_REMATCH[4]}" + fi + if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+[A-Za-z0-9_.-]*$ ]]; then + echo "::error::'$VERSION' is not a version like 0.11.9_beta." + exit 1 + fi + TAG="API_v$VERSION" + if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then + if [ "$DRY_RUN" = true ]; then + echo "::warning::$TAG already exists, so a real release would stop here. Dry run continues." + else + echo "::error::$TAG already exists. Leave the version blank for the next one, or type another." + exit 1 + fi + fi + { + echo "version=$VERSION" + echo "tag=$TAG" + echo "previous_tag=$PREVIOUS_TAG" + } >> "$GITHUB_OUTPUT" + echo "Releasing $VERSION as $TAG (notes since ${PREVIOUS_TAG:-the first commit})" + + - name: Check the hardware test (HIL) result + id: hil + env: + GH_TOKEN: ${{ github.token }} + WAIVER: ${{ inputs.hil_waiver }} + run: | + context=java-hil + if [ -n "$WAIVER" ] && ! [[ "$WAIVER" =~ ^[A-Z][A-Z0-9]+-[0-9]+$ ]]; then + echo "::error::hil_waiver must be a Jira key such as DEV-1234, not '$WAIVER'." + exit 1 + fi + # Newest first: the latest result for this context on this exact commit decides. + line=$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/statuses" --paginate \ + --jq '.[] | [.context, .state, .description] | @tsv' | awk -F'\t' -v c="$context" '$1 == c { print; exit }') + state=$(printf '%s' "$line" | cut -f2) + description=$(printf '%s' "$line" | cut -f3) + if [ "$state" = success ]; then + echo "Hardware test passed on $GITHUB_SHA: $description" + echo "hil=Tested on hardware before release: $description." >> "$GITHUB_OUTPUT" + elif [ -n "$WAIVER" ]; then + echo "::warning::No passing '$context' on $GITHUB_SHA (found: ${state:-none}); released under waiver $WAIVER." + echo "hil=Released without a passing hardware test (HIL), waived under $WAIVER." >> "$GITHUB_OUTPUT" + elif [ "$DRY_RUN" = true ]; then + echo "::warning::No passing '$context' on $GITHUB_SHA (found: ${state:-none}). A real release would stop here." + else + echo "::error::No passing '$context' on $GITHUB_SHA (found: ${state:-none}${description:+: $description}). On the bench, at this commit, run: tools/hil/run-java-hil.ps1 -Report. Then run this workflow again, or give a Jira key in hil_waiver." + exit 1 + fi + + - name: Set up JDK 11 + uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4.9.1 + with: + java-version: '11' + distribution: 'temurin' + + # Same pinned action as gradle.yml, and likewise no gradle-version: build through the + # committed wrapper. + - name: Setup Gradle + uses: gradle/actions/setup-gradle@ec92e829475ac0c2315ea8f9eced72db85bb337a # v3.0.0 + + - name: Test ShimmerDriver + working-directory: ShimmerDriver + run: ./gradlew test + + # ShimmerDriverPC includes :ShimmerDriver and :ShimmerBluetoothManager as subprojects. + - name: Build ShimmerDriverPC + working-directory: ShimmerDriverPC + run: ./gradlew build + + publish: + needs: build + if: github.event_name == 'workflow_dispatch' && !inputs.dry_run + runs-on: ubuntu-latest + timeout-minutes: 30 # a hung Gradle daemon otherwise holds the runner for 6 hours + permissions: + contents: read + packages: write + env: + VERSION: ${{ needs.build.outputs.version }} + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + with: + persist-credentials: false # publish gets its token explicitly, below + + - name: Set up JDK 11 + uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4.9.1 + with: + java-version: '11' + distribution: 'temurin' + + - name: Setup Gradle + uses: gradle/actions/setup-gradle@ec92e829475ac0c2315ea8f9eced72db85bb337a # v3.0.0 + + # `publish` runs in every project of the ShimmerDriverPC build, so all three artifacts go + # out in one invocation, and -PreleaseVersion versions all three (and their POM + # dependencies on each other). It builds the jars but does not re-run the tests, which the + # build job ran on this same commit. The build files read the credentials from USERNAME and TOKEN. + - name: Publish to GitHub Packages + working-directory: ShimmerDriverPC + env: + USERNAME: ${{ github.actor }} + TOKEN: ${{ github.token }} + run: ./gradlew publish -PreleaseVersion="$VERSION" + + # The jars just published, so the GitHub Release carries the same files as GitHub Packages. + - name: Collect the published jars + run: | + mkdir -p release-assets + cp ShimmerDriver/build/libs/ShimmerDriver.jar "release-assets/shimmerdriver-$VERSION.jar" + cp ShimmerBluetoothManager/build/libs/ShimmerBluetoothManager.jar "release-assets/shimmerbluetoothmanager-$VERSION.jar" + cp ShimmerDriverPC/build/libs/ShimmerDriverPC.jar "release-assets/shimmerdriverpc-$VERSION.jar" + ls -l release-assets + + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: release-jars + path: release-assets/ + if-no-files-found: error + + matlab-jar: + needs: build + runs-on: ubuntu-latest + timeout-minutes: 30 # a hung Gradle daemon otherwise holds the runner for 6 hours + permissions: + contents: read + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + with: + persist-credentials: false # the Gradle build needs no git credentials + + - name: Set up JDK 11 + uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4.9.1 + with: + java-version: '11' + distribution: 'temurin' + + - name: Setup Gradle + uses: gradle/actions/setup-gradle@ec92e829475ac0c2315ea8f9eced72db85bb337a # v3.0.0 + + - name: Build ShimmerJavaClass.jar for MATLAB (Java 8 bytecode) + working-directory: ShimmerDriverPC + run: ./gradlew shadowJar -PmatlabJava8 + + # Every class in the jar, dependencies included, since a dependency built for a later Java + # breaks MATLAB just as surely as our own code would (~32,500 classes, about 2 s). + - name: Check every class in the jar is Java 8 bytecode + run: | + jar=ShimmerDriverPC/build/libs/ShimmerJavaClass.jar + python3 - "$jar" <<'EOF' + import struct, sys, zipfile + + MAIN = "com/shimmerresearch/tools/matlab/ShimmerJavaClass.class" + jar = sys.argv[1] + checked, bad = 0, [] + with zipfile.ZipFile(jar) as z: + names = z.namelist() + if MAIN not in names: + print(f"::error::{jar} does not contain {MAIN}.") + sys.exit(1) + for name in names: + # Java 8 never loads module descriptors or multi-release entries for later Javas. + if (not name.endswith(".class") or name.startswith("META-INF/versions/") + or name.endswith("module-info.class")): + continue + with z.open(name) as f: + head = f.read(8) + checked += 1 + if len(head) < 8 or head[:4] != b"\xca\xfe\xba\xbe": + bad.append((name, "not a class file")) + elif struct.unpack(">H", head[6:8])[0] > 52: + bad.append((name, f"class version {struct.unpack('>H', head[6:8])[0]}")) + print(f"Checked {checked} classes; {len(bad)} newer than Java 8 (class version 52).") + for name, why in bad[:20]: + print(f"::error::{name}: {why}. MATLAB on Java 8 cannot load it.") + if len(bad) > 20: + print(f"::error::...and {len(bad) - 20} more.") + sys.exit(1 if bad else 0) + EOF + mkdir -p matlab-jar + cp "$jar" matlab-jar/ShimmerJavaClass.jar + ls -l matlab-jar + + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: matlab-jar + path: matlab-jar/ + if-no-files-found: error + + release: + needs: [build, publish, matlab-jar] + if: github.event_name == 'workflow_dispatch' && !inputs.dry_run + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write # create the tag and the release + env: + GH_TOKEN: ${{ github.token }} + VERSION: ${{ needs.build.outputs.version }} + TAG: ${{ needs.build.outputs.tag }} + PREVIOUS_TAG: ${{ needs.build.outputs.previous_tag }} + HIL: ${{ needs.build.outputs.hil }} + steps: + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: release-jars + path: release-assets + + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: matlab-jar + path: matlab-jar + + - name: Create the tag and GitHub Release + run: | + cp matlab-jar/ShimmerJavaClass.jar "release-assets/ShimmerJavaClass-$VERSION.jar" + # The generated notes, with the hardware test result (or its waiver) in front. + args=(-f tag_name="$TAG" -f target_commitish="$GITHUB_SHA") + if [ -n "$PREVIOUS_TAG" ]; then args+=(-f previous_tag_name="$PREVIOUS_TAG"); fi + { + if [ -n "$HIL" ]; then + echo "$HIL" + echo + fi + gh api "repos/$GITHUB_REPOSITORY/releases/generate-notes" "${args[@]}" --jq .body + } > notes.md + gh release create "$TAG" release-assets/* \ + --repo "$GITHUB_REPOSITORY" \ + --target "$GITHUB_SHA" \ + --title "Shimmer Java API Rev $VERSION" \ + --notes-file notes.md \ + --latest=false + { + echo "### Released Java API $VERSION" + echo "- Release: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/tag/$TAG" + echo "- Packages: com.shimmerresearch:shimmerdriver, shimmerbluetoothmanager and shimmerdriverpc at $VERSION" + echo "- ${HIL:-No hardware test result}" + echo "- Next: merge the MATLAB PR, then run Release Android API in ShimmerAndroidAPI; it builds against $VERSION unless you pick another driver version." + } >> "$GITHUB_STEP_SUMMARY" + + update-matlab: + needs: [build, release] + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: {} # writes to Shimmer-MATLAB-ID with MATLAB_REPO_TOKEN, not this repo's token + env: + VERSION: ${{ needs.build.outputs.version }} + TAG: ${{ needs.build.outputs.tag }} + MATLAB_REPO: ShimmerResearch/Shimmer-MATLAB-ID + BRANCH: ShimmerJavaClass_${{ needs.build.outputs.version }} + HAS_TOKEN: ${{ secrets.MATLAB_REPO_TOKEN != '' }} + steps: + - name: Check for MATLAB_REPO_TOKEN + if: env.HAS_TOKEN != 'true' + run: | + echo "::error::Secret MATLAB_REPO_TOKEN is not set, so the Shimmer-MATLAB-ID PR cannot be opened. Add a fine-grained token for $MATLAB_REPO (Contents and Pull requests: read/write) as a repo secret, then re-run this job." + exit 1 + + # Credentials stay persisted here on purpose: the git push below uses them. Nothing else runs + # in this job. + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + with: + repository: ${{ env.MATLAB_REPO }} + token: ${{ secrets.MATLAB_REPO_TOKEN }} + path: matlab + + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: matlab-jar + path: matlab-jar + + - name: Open the PR updating libs/ShimmerJavaClass.jar + env: + GH_TOKEN: ${{ secrets.MATLAB_REPO_TOKEN }} + working-directory: matlab + run: | + existing=$(gh pr list --repo "$MATLAB_REPO" --head "$BRANCH" --state open --json url --jq '.[0].url // ""') + if [ -n "$existing" ]; then + echo "PR already open: $existing" + echo "- MATLAB PR: $existing" >> "$GITHUB_STEP_SUMMARY" + exit 0 + fi + cp ../matlab-jar/ShimmerJavaClass.jar libs/ShimmerJavaClass.jar + if git diff --quiet -- libs/ShimmerJavaClass.jar; then + echo "libs/ShimmerJavaClass.jar is already this build; no PR needed." + exit 0 + fi + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git switch -c "$BRANCH" + git add libs/ShimmerJavaClass.jar + git commit -m "Update ShimmerJavaClass.jar to Shimmer Java API $VERSION" \ + -m "Built by $GITHUB_REPOSITORY's Release workflow from $TAG ($GITHUB_SHA), as Java 8 bytecode." + git push --force origin "HEAD:refs/heads/$BRANCH" + url=$(gh pr create --repo "$MATLAB_REPO" --base master --head "$BRANCH" \ + --title "Update ShimmerJavaClass.jar to Shimmer Java API $VERSION" \ + --body "Replaces \`libs/ShimmerJavaClass.jar\` with the build from [$TAG]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/tag/$TAG) (\`$GITHUB_SHA\`), compiled as Java 8 bytecode with \`gradlew shadowJar -PmatlabJava8\`. + + Opened by the [Release Java API run]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID).") + echo "Opened $url" + echo "- MATLAB PR: $url" >> "$GITHUB_STEP_SUMMARY" diff --git a/.gitignore b/.gitignore index 19c5b1390..a480c7ae5 100644 --- a/.gitignore +++ b/.gitignore @@ -55,3 +55,7 @@ ShimmerAndroidInstrumentDriver/gen/com/shimmerresearch/androidinstrumentdriver/B ShimmerAndroidInstrumentDriver/gen/com/shimmerresearch/androidinstrumentdriver/R.java gradle.properties github.properties + +# Java HIL (tools/hil): the local rig file and run output +tools/hil/rig-java.json +tools/hil/out/ diff --git a/AGENTS.md b/AGENTS.md index 5e47628f6..987a978b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,27 @@ all: they are legacy Eclipse ADT Android projects. Test results land in `**/build/test-results/test/*.xml`. +## Releasing +Releases are cut by the **Release Java API** workflow (`release.yml`), not from a developer machine, +and need no uprev PR: +1. Run the workflow on `master`. Leave `version` blank for the next patch after the last `API_v` + release, or type one. It tests and builds as CI does, publishes all three artifacts to GitHub + Packages in one `gradlew publish`, tags `API_v`, and creates the GitHub Release with the + jars attached (not marked Latest — that stays with Consensys). +2. It also builds `ShimmerJavaClass.jar` for MATLAB and opens a PR replacing + `Shimmer-MATLAB-ID/libs/ShimmerJavaClass.jar` (needs the `MATLAB_REPO_TOKEN` secret). Review and + merge it. +3. Run `ShimmerAndroidAPI`'s own Release workflow, which builds against the newest Java release unless + told otherwise. + +The version is not stored in the source: the three publishing blocks read `-PreleaseVersion`, which +the workflow passes, and fall back to `local`. The `API_v` tags are the record of what was released. + +`ShimmerJavaClass.jar` must be Java 8 bytecode, because MATLAB may load it on Java 8. Build it locally +with `cd ShimmerDriverPC && ./gradlew shadowJar -PmatlabJava8`, which compiles all three projects with +`--release 8` — that also rejects any API newer than Java 8, so `Process.onExit()`, `var` and the like +fail the build here instead of throwing `NoSuchMethodError` inside MATLAB. + ## Subprojects | Project | Role | |---|---| diff --git a/README.md b/README.md index ab212feab..708d6f538 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,12 @@ Best examples to start with are For help with using on Ubuntu please check the [wiki](https://github.com/ShimmerEngineering/Shimmer-Java-Android-API/wiki). +## Hardware tests + +[`tools/hil`](tools/hil/README.md) runs the driver on real Shimmer3 and Shimmer3R units over +Bluetooth Classic: streaming, SD logging and in-stream commands while streaming, and reconnects, with +the driver's timers on. **Release Java API** requires a passing run on the commit it releases. + Rev 3.00 - Change to Handler MSGs diff --git a/ShimmerBluetoothManager/build.gradle b/ShimmerBluetoothManager/build.gradle index b5ed8183e..6bf3cb637 100644 --- a/ShimmerBluetoothManager/build.gradle +++ b/ShimmerBluetoothManager/build.gradle @@ -27,7 +27,7 @@ publishing { groupId = 'com.shimmerresearch' // Replace with your package's group/organization name artifactId = 'shimmerbluetoothmanager' // Replace with the name of your package - version = '0.11.8_beta' // Replace with your package version + version = project.findProperty('releaseVersion') ?: 'local' // set by the Release Java API workflow (-PreleaseVersion) // Jar publication //( @@ -40,7 +40,7 @@ publishing { repositories { maven { name = "GitHubPackages" - url = uri("https://maven.pkg.github.com/ShimmerEngineering/Shimmer-Java-Android-API") + url = uri("https://maven.pkg.github.com/ShimmerResearch/Shimmer-Java-Android-API") credentials { /* Create gradle.properties file in GRADLE_USER_HOME/.gradle/ (e.g. C:/Users/YourUsername/.gradle/) with the two lines listed below. Fill in your @@ -68,3 +68,14 @@ dependencies { // 'test.useTestNG()' to your build script. testImplementation 'junit:junit:4.12' } + +// Without -PreleaseVersion the version is 'local', and GitHub Packages never lets a version be +// overwritten. Releases go through the Release Java API workflow; publishToMavenLocal is unaffected. +tasks.withType(PublishToMavenRepository).configureEach { + doFirst { + if (publication.version == 'local') { + throw new GradleException("Refusing to publish ${publication.artifactId} as version 'local'. " + + "Release with the Release Java API workflow, or pass -PreleaseVersion.") + } + } +} diff --git a/ShimmerDriver/build.gradle b/ShimmerDriver/build.gradle index 8cce51299..8d62a7215 100644 --- a/ShimmerDriver/build.gradle +++ b/ShimmerDriver/build.gradle @@ -49,7 +49,7 @@ publishing { groupId = 'com.shimmerresearch' // Replace with your package's group/organization name artifactId = 'shimmerdriver' // Replace with the name of your package - version = '0.11.8_beta' // Replace with your package version + version = project.findProperty('releaseVersion') ?: 'local' // set by the Release Java API workflow (-PreleaseVersion) // Jar publication //( @@ -63,7 +63,7 @@ publishing { repositories { maven { name = "GitHubPackages" - url = uri("https://maven.pkg.github.com/ShimmerEngineering/Shimmer-Java-Android-API") + url = uri("https://maven.pkg.github.com/ShimmerResearch/Shimmer-Java-Android-API") credentials { /* Create gradle.properties file in GRADLE_USER_HOME/.gradle/ (e.g. C:/Users/YourUsername/.gradle/) with the two lines listed below. Fill in your @@ -173,3 +173,14 @@ tasks.withType(Test).configureEach { } } + +// Without -PreleaseVersion the version is 'local', and GitHub Packages never lets a version be +// overwritten. Releases go through the Release Java API workflow; publishToMavenLocal is unaffected. +tasks.withType(PublishToMavenRepository).configureEach { + doFirst { + if (publication.version == 'local') { + throw new GradleException("Refusing to publish ${publication.artifactId} as version 'local'. " + + "Release with the Release Java API workflow, or pass -PreleaseVersion.") + } + } +} diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 078ceb982..0b7b49c01 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -76,6 +76,7 @@ import java.io.ByteArrayOutputStream; import java.io.IOException; +import java.io.ObjectInputStream; import java.io.Serializable; import java.nio.ByteBuffer; import java.util.ArrayList; @@ -186,7 +187,7 @@ public String toString() { protected byte mCurrentCommand; protected boolean mWaitForAck=false; // This indicates whether the device is waiting for an acknowledge packet from the Shimmer Device protected boolean mWaitForResponse=false; // This indicates whether the device is waiting for a response packet from the Shimmer Device - protected boolean mTransactionCompleted=true; // Variable is used to ensure a command has finished execution prior to executing the next command (see initialize()) + protected volatile boolean mTransactionCompleted=true; // Variable is used to ensure a command has finished execution prior to executing the next command (see initialize()). Volatile: operationPrepare() waits on it from an app thread transient protected IOThread mIOThread; transient protected ProcessingThread mPThread; @Deprecated // mContinousSync doesn't do anything @@ -200,8 +201,12 @@ public String toString() { private boolean mUseLegacyDelayToDelayForResponse = false; - ArrayBlockingQueue mABQPacketByeArray = new ArrayBlockingQueue(10000); - public List mListofPCTimeStamps = new ArrayList(); + // The connection's queues are transient: the IO thread and the timers change them while a + // connected device is serialised by deepClone(), which threw ConcurrentModificationException + // (DEV-1310). readObject() gives a copy empty ones. + private static final int PACKET_QUEUE_CAPACITY = 10000; + transient ArrayBlockingQueue mABQPacketByeArray = new ArrayBlockingQueue(PACKET_QUEUE_CAPACITY); + public transient List mListofPCTimeStamps = new ArrayList(); protected boolean mIamAlive = false; protected abstract void connect(String address,String bluetoothLibrary); @@ -233,7 +238,7 @@ public String toString() { private SystemTimestampPlot systemTimestampPlot = new SystemTimestampPlot(); - private List mListofInstructions = new ArrayList(); + private transient List mListofInstructions = new ArrayList(); private final int ACK_TIMER_DURATION = 2; // Duration to wait for an ack packet (seconds) protected boolean mDummyRead = false, mDummyReadStarted = false; @Deprecated @@ -584,71 +589,94 @@ public ShimmerBluetooth(String userAssignedName, double samplingRate, int enable } public class ProcessingThread extends Thread { - public boolean stop = false; + public volatile boolean stop = false; int count=0; public void run() { - while (!stop) { - if(!mABQPacketByeArray.isEmpty()){ + while (!stop && !Thread.currentThread().isInterrupted()) { + RawBytePacketWithPCTimeStamp rbp = null; + try { + // Blocks (with a timeout) instead of busy-spinning on isEmpty() while idle. + // The timeout ensures the stop flag is still checked periodically. + rbp = mABQPacketByeArray.poll(100, TimeUnit.MILLISECONDS); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + if(rbp!=null){ count++; if(count%1000==0){ consolePrintLn("Queue Size: " + mABQPacketByeArray.size()); printLogDataForDebugging("Queue Size: " + mABQPacketByeArray.size() + "\n"); } - RawBytePacketWithPCTimeStamp rbp = mABQPacketByeArray.remove(); // buildAndSendMsg(rbp.mDataArray, FW_TYPE_BT, false, rbp.mSystemTimeStamp); buildAndSendMsg(rbp.mDataArray, COMMUNICATION_TYPE.BLUETOOTH, false, rbp.mSystemTimeStamp); } - } - } - } + } + } + } //region --------- BLUETOOH STACK --------- public class IOThread extends Thread { protected byte[] byteBuffer = {0}; - public boolean stop = false; + public volatile boolean stop = false; public void run() { - while(!stop) { + while(!stop && !Thread.currentThread().isInterrupted()) { + boolean didWork = false; //In-Shimmer Test here if(InShimmerTest) { if (bytesAvailableToBeRead()) { - byte[] data = readBytes(availableBytes()); - if (data!=null) { - if (data.length>0) { - if (mTestByteListener != null) { - mTestByteListener.eventNewBytesReceived(data); - } + didWork = true; + byte[] data = readBytes(availableBytes()); + if (data!=null) { + if (data.length>0) { + if (mTestByteListener != null) { + mTestByteListener.eventNewBytesReceived(data); + } + } } } - } } else { if (mDummyRead) { performDummyRead(); + didWork = true; } - + // Process Instruction on stack. is an instruction running? if not proceed if(!isInstructionStackLock()){ - processNextInstruction(); + if(processNextInstruction()){ + didWork = true; + } } - + if(mIsStreaming){ processWhileStreaming(); + didWork = true; } else if(bytesAvailableToBeRead()){ + didWork = true; if(mWaitForAck) { processNotStreamingWaitForAck(); - } + } else if(mWaitForResponse) { processNotStreamingWaitForResp(); - } - + } + processBytesAvailableAndInstreamSupported(); - + + } + } + + if(!didWork){ + // Nothing useful happened this iteration (idle, not streaming, no pending + // instructions/bytes) - avoid busy-spinning and pegging a CPU core. + try { + Thread.sleep(2); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); } } - } } @@ -681,10 +709,16 @@ private void performDummyRead() { mDummyReadStarted = false; } - private void processNextInstruction() { + /** + * @return true if an instruction was found and processed (i.e. useful work was done), + * or if this call already idle-paced the loop with its own threadSleep(50) below - + * in that case reporting true here stops run()'s outer idle-sleep from stacking an + * additional wait on top of this one. + */ + private boolean processNextInstruction() { // check instruction stack, are there any other instructions left to be executed? //checkAndRemoveFirstInstructionIfNull(); - + byte[] insBytes = getInstruction(); if (insBytes!=null){ mCurrentCommand=insBytes[0]; @@ -761,14 +795,32 @@ else if((mCurrentCommand==GET_FW_VERSION_COMMAND) mTransactionCompleted=false; + return true; } else { + // getInstruction() returned null here - either the instruction stack is + // genuinely empty, or its leading entry was a null placeholder that + // getInstruction() just removed (a real instruction may still be next in + // the list and will be picked up on the following iteration). Either way, + // if there's also nothing else to do this iteration, wait here rather than + // busy-spinning. if (!mIsStreaming && !bytesAvailableToBeRead()){ - threadSleep(50); + // Report "did work" (true) so the caller's own idle sleep in run() + // doesn't stack an extra wait on top of this one. + // Not threadSleep(): that helper swallows InterruptedException without + // restoring the interrupt flag, which would defeat run()'s + // !Thread.currentThread().isInterrupted() loop-exit check. + try { + Thread.sleep(50); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + return true; } + return false; } } - - /** Process ACK from a GET or SET command while not streaming */ + + /** Process ACK from a GET or SET command while not streaming */ private void processNotStreamingWaitForAck() { //JC TEST:: IMPORTANT TO REMOVE // This is to simulate packet loss /* @@ -811,13 +863,21 @@ private void processNotStreamingWaitForAck() { clearSerialBuffer(); - hasStopStreaming(); + hasStopStreaming(); removeInstruction(0); removeAllNulls(); if (mCurrentCommand==STOP_SDBT_COMMAND){ - eventLogAndStreamStatusChanged(mCurrentCommand); + eventLogAndStreamStatusChanged(mCurrentCommand); } setInstructionStackLock(false); + // The stop is handled and the STOP retired. The byte that started the handling + // must not also go on to the ACK processing below: when it was the unit's ACK, + // that retired the next instruction as well, a command queued straight after + // stopStreaming() that was never sent (DEV-1306) + if((byte)byteBuffer[0]==ACK_COMMAND_PROCESSED){ + printLogDataForDebugging("Stop handled on its ACK, the first byte back"); + } + return; } // //TODO: ACK is probably now working for STOP_STREAMING_COMMAND so merge in with others? // if(mCurrentCommand==STOP_SDBT_COMMAND) { //due to not receiving the ack from stop streaming command we will skip looking for it. @@ -1005,22 +1065,34 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR printLogDataForDebugging("COMMAND TXed and ACK RECEIVED IN STREAM"); printLogDataForDebugging("INS CMD RESP"); - //Firstly handle the in-stream response - stopTimerCheckForAckOrResp(); //cancel the ack timer - mWaitForResponse=false; - mWaitForAck=false; + // The firmware also sends a status response unprompted (on a dock or + // undock, the user button, a low-battery stop), so this completes the + // command in flight only if the response is that command's reply + byte[] inStreamResponseCommand = readBytes(1, INSTREAM_CMD_RESPONSE); + boolean isReplyToCommandInFlight = inStreamResponseCommand!=null + && isReplyToCommandInFlight(inStreamResponseCommand[0]); + if(isReplyToCommandInFlight){ + stopTimerCheckForAckOrResp(); //cancel the ack timer + mWaitForResponse=false; + mWaitForAck=false; + } - processInstreamResponse(true); + //Firstly handle the in-stream response + if(inStreamResponseCommand!=null){ + processInstreamResponse(inStreamResponseCommand[0], true); + } - // Need to remove here because it is an - // in-stream response while streaming so not - // handled elsewhere - if(getListofInstructions().size()>0){ - removeInstruction(0); + if(isReplyToCommandInFlight){ + // Need to remove here because it is an + // in-stream response while streaming so not + // handled elsewhere + if(getListofInstructions().size()>0){ + removeInstruction(0); + } + + mTransactionCompleted=true; + setInstructionStackLock(false); } - - mTransactionCompleted=true; - setInstructionStackLock(false); //Then process the Data packet processDataPacket(bufferTemp); @@ -1060,10 +1132,89 @@ protected void processWhileStreaming() { printLogDataForDebugging("readbyte null"); } + if(processAckAtStartOfBuffer()){ + return; + } + //If there is a full packet and the subsequent sequence number of following packet if(mByteArrayOutputStream.size()>=getPacketSizeWithCrc()+2){ // +2 because there are two acks processPacket(); - } + } + } + + /** + * Handles an ACK at the very start of the buffer, with no data packet before + * it. The unit sends one when it answers while its data packets are paused, as + * they are for about 100 ms while it closes its SD file after + * STOP_LOGGING_ONLY_COMMAND (DEV-1291). processPacket() only looks for an ACK + * after a data packet, so it threw such a reply away; the command then timed + * out, and the timeout dropped every queued instruction. + *

+ * It is taken only while a command waits for its ACK, and only when the bytes + * after it are what that command expects: its own in-stream reply (FF 8A and + * then its response opcode), or for a SET command a bare ACK whose link CRC + * checks out. A 0xFF data byte the parser resyncs onto is therefore not taken + * for one. Without a link CRC a bare ACK can't be told from a data byte, but + * then the previous ACK isn't processed until the stream resumes either, so the + * next command never goes out during the pause. + * + * @return true while the bytes so far are taken, or may still turn out to be + * such an ACK. The buffer is then at most 3 bytes, too short for + * processPacket() anyway. + */ + private boolean processAckAtStartOfBuffer() { + if(!mWaitForAck || mByteArrayOutputStream.size()==0){ + return false; + } + byte[] bufferTemp = mByteArrayOutputStream.toByteArray(); + if(bufferTemp[0]!=ACK_COMMAND_PROCESSED){ + return false; + } + if(bufferTemp.length==1){ + return true; //wait for what follows the ACK + } + + //The in-stream reply to the GET command in flight + if(isSupportedInStreamCmds() && bufferTemp[1]==INSTREAM_CMD_RESPONSE){ + if(bufferTemp.length==2){ + return true; //wait for the response opcode + } + if(bufferTemp.length>3 || !isReplyToCommandInFlight(bufferTemp[2])){ + return false; + } + printLogDataForDebugging("COMMAND TXed and ACK RECEIVED IN STREAM, with no data packet before it"); + stopTimerCheckForAckOrResp(); //cancel the ack timer + mWaitForResponse=false; + mWaitForAck=false; + + //Reads the rest of the response, and its CRC, from the port + processInstreamResponse(bufferTemp[2], true); + + if(getListofInstructions().size()>0){ + removeInstruction(0); + } + mTransactionCompleted=true; + setInstructionStackLock(false); + clearBuffers(); + return true; + } + + //A bare ACK to the SET command in flight + if(isKnownSetCommand(mCurrentCommand) && mBtCommsCrcModeCurrent!=BT_CRC_MODE.OFF){ + int numCrcBytes = mBtCommsCrcModeCurrent.getNumCrcBytes(); + for(int i=1;i { - int code = p.exitValue(); - System.err.println("[BLEGrpcServer] exited: code=" + code + - (code >= 128 ? " (likely signal " + (code - 128) + ")" : "")); - }); + // Not Process.onExit(): that is Java 9+, and MATLAB loads this class on Java 8 via + // ShimmerJavaClass.jar, where it throws NoSuchMethodError. Daemon, like onExit()'s pool thread. + final Process process = runningProcess; + Thread exitWatcher = new Thread(() -> { + try { + int code = process.waitFor(); + System.err.println("[BLEGrpcServer] exited: code=" + code + + (code >= 128 ? " (likely signal " + (code - 128) + ")" : "")); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + }, "BLEGrpcServer-exit"); + exitWatcher.setDaemon(true); + exitWatcher.start(); processThread.start(); return port; diff --git a/ShimmerDriverPC/build.gradle b/ShimmerDriverPC/build.gradle index 00ee312ac..b452317e4 100644 --- a/ShimmerDriverPC/build.gradle +++ b/ShimmerDriverPC/build.gradle @@ -32,19 +32,41 @@ repositories { test { // this test requires a physical Shimmer2r to run exclude '**/API_00001_ShimmerPC_GeneralBluetoothShimmer2R.class' - exclude '**/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_only.class' - exclude '**/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_master.class' - exclude '**/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_slave.class' + // the hardware-in-the-loop scenarios need a unit; hilTest runs them (tools/hil/run-java-hil.ps1) + exclude '**/hil/JavaHilScenariosTest.class' +} + +// Hardware-in-the-loop scenarios on a real Shimmer over a paired Bluetooth serial port, run by +// tools/hil/run-java-hil.ps1 (see tools/hil/README.md). Each -Phil.= reaches the tests +// as the system property hil.. +tasks.register('hilTest', Test) { + description = 'Runs the hardware-in-the-loop scenarios on a real unit (tools/hil/run-java-hil.ps1)' + testClassesDirs = sourceSets.test.output.classesDirs + classpath = sourceSets.test.runtimeClasspath + include '**/hil/JavaHilScenariosTest.class' + dependsOn 'testClasses' + systemProperties project.properties.findAll { k, v -> k.startsWith('hil.') } + outputs.upToDateWhen { false } + testLogging { + events 'passed', 'skipped', 'failed' + showStandardStreams = true + exceptionFormat 'full' + } } publishing { publications { mavenJava(MavenPublication) { from components.java + // The Shadow plugin adds ShimmerJavaClass.jar (no classifier) to components.java, where it + // collides with the plain jar and fails publish on Gradle 8. Publish the plain jar with its + // dependencies in the POM, as releases up to 0.11.7_beta did; the fat jar goes to MATLAB + // and the GitHub Release instead. + components.java.withVariantsFromConfiguration(configurations.shadowRuntimeElements) { skip() } groupId = 'com.shimmerresearch' // Replace with your package's group/organization name artifactId = 'shimmerdriverpc' // Replace with the name of your package - version = '0.11.8_beta' // Replace with your package version + version = project.findProperty('releaseVersion') ?: 'local' // set by the Release Java API workflow (-PreleaseVersion) // Jar publication //( @@ -57,7 +79,7 @@ publishing { repositories { maven { name = "GitHubPackages" - url = uri("https://maven.pkg.github.com/ShimmerEngineering/Shimmer-Java-Android-API") + url = uri("https://maven.pkg.github.com/ShimmerResearch/Shimmer-Java-Android-API") credentials { /* Create gradle.properties file in GRADLE_USER_HOME/.gradle/ (e.g. C:/Users/YourUsername/.gradle/) with the two lines listed below. Fill in your @@ -101,6 +123,8 @@ dependencies { // testCompile dependency to testCompile 'org.testng:testng:6.8.1' and add // 'test.useTestNG()' to your build script. testImplementation 'junit:junit:4.12' + // the HIL reports (src/test/java/com/shimmerresearch/hil) + testImplementation 'com.google.code.gson:gson:2.10.1' implementation 'com.parse.bolts:bolts-tasks:1.4.0' // https://mvnrepository.com/artifact/org.bouncycastle/bcpkix-jdk15on @@ -110,12 +134,18 @@ dependencies { implementation("org.bouncycastle:bcprov-jdk15on:1.61") } -// Shadow JAR task to create a runnable JAR with dependencies -/* -Change to using the following below for ShimmerDriverPC/ShimmerDriver/ShimmerBluetoothManager -sourceCompatibility = '1.8' // Ensure code is compiled with Java 8 -targetCompatibility = '1.8' // Ensure bytecode is compatible with Java 8 -*/ +// Shadow JAR task to create a runnable JAR with dependencies. +// ShimmerJavaClass.jar is loaded by MATLAB, which may run it on Java 8, so build it as Java 8 +// bytecode with: ./gradlew shadowJar -PmatlabJava8 +// This applies to the ShimmerDriver and ShimmerBluetoothManager subprojects too, so their build files +// no longer need editing to 1.8 by hand. --release 8 also fails the compile if the code uses an API +// newer than Java 8, which sourceCompatibility = '1.8' alone would let through to fail in MATLAB. +// The "Release Java API" workflow builds the jar this way and opens a PR into Shimmer-MATLAB-ID/libs. +if (hasProperty('matlabJava8')) { + allprojects { + tasks.withType(JavaCompile).configureEach { options.release = 8 } + } +} shadowJar { archiveBaseName.set('ShimmerJavaClass') // Use archiveBaseName instead of baseName archiveClassifier.set('') // Remove classifier so it’s named shimmerjavaclass.jar @@ -126,3 +156,14 @@ shadowJar { mergeServiceFiles() // Merges service files (if any) } + +// Without -PreleaseVersion the version is 'local', and GitHub Packages never lets a version be +// overwritten. Releases go through the Release Java API workflow; publishToMavenLocal is unaffected. +tasks.withType(PublishToMavenRepository).configureEach { + doFirst { + if (publication.version == 'local') { + throw new GradleException("Refusing to publish ${publication.artifactId} as version 'local'. " + + "Release with the Release Java API workflow, or pass -PreleaseVersion.") + } + } +} diff --git a/ShimmerDriverPC/src/main/java/com/shimmerresearch/guiUtilities/plot/BasicPlotManagerPC.java b/ShimmerDriverPC/src/main/java/com/shimmerresearch/guiUtilities/plot/BasicPlotManagerPC.java index e7b8881a0..eea07eb7f 100644 --- a/ShimmerDriverPC/src/main/java/com/shimmerresearch/guiUtilities/plot/BasicPlotManagerPC.java +++ b/ShimmerDriverPC/src/main/java/com/shimmerresearch/guiUtilities/plot/BasicPlotManagerPC.java @@ -55,6 +55,10 @@ import java.util.Timer; import java.util.TimerTask; +import java.util.concurrent.atomic.AtomicBoolean; + +import javax.swing.SwingUtilities; + import org.apache.commons.collections.buffer.CircularFifoBuffer; import com.shimmerresearch.driver.FormatCluster; @@ -82,10 +86,21 @@ public class BasicPlotManagerPC extends AbstractPlotManager { public HashMap mMapofHalfWindowSize = new HashMap(); + /** Default stroke width for continuous traces. A plot manager can override it for the traces it + * creates with {@link #setTraceLineThickness(float)}. */ public static float DEFAULT_LINE_THICKNESS=2; - protected double mCurrentXValue = 0; - protected boolean mIsPlotPaused = false; + /** DEV-896: stroke width this plot manager gives continuous traces, DEFAULT_LINE_THICKNESS + * unless {@link #setTraceLineThickness(float)} was called. */ + private float mTraceLineThickness = DEFAULT_LINE_THICKNESS; + + /** X value (for the time axis: System_Timestamp_Plot, epoch ms) of the most recently plotted + * sample. Written by the data thread in filterDataAndPlot(); volatile because the live-viewport + * frame clock reads it on the EDT (DEV-896). */ + protected volatile double mCurrentXValue = 0; + /** volatile: set from GUI handlers but read by the live-viewport frame clock tick on the EDT + * and by the data thread, which may not be the thread that set it (DEV-896). */ + protected volatile boolean mIsPlotPaused = false; public boolean mIsLegendLabelsPainted = true; public boolean mIsScaleLabelsPainted = true; public boolean mIsAxisLabelsPainted = true; @@ -346,10 +361,25 @@ private ITrace2D addBarTrace(Chart2D chart, int plotMaxSize) { return trace; } + /** DEV-896: stroke width for continuous traces this plot manager creates from now on, and for + * traces later set to CONTINUOUS/INDIVIDUAL_POINTS via setTraceLineStyle(). Existing traces + * keep their stroke, so call it before signals are added. + *

Cost: jchart2d paints a trace with TracePainterPolyline, i.e. Graphics.drawPolyline, + * antialiasing off. One paint of 2560 points at UHD measured ~0.4 ms at 1 px against ~3.7 ms at + * 2 px at identity transform (the installed DPI-unaware exe, LauncherConsensysInternal's + * uiScale=1.0), and ~3.5 ms against ~4.0 ms at uiScale 2, where even 1 px is scaled. */ + public void setTraceLineThickness(float thickness){ + mTraceLineThickness = thickness; + } + + public float getTraceLineThickness(){ + return mTraceLineThickness; + } + private ITrace2D createNormalTrace(int plotMaxSize) { Trace2DLtd trace = new Trace2DLtdMonotonicX(plotMaxSize); //DEV-896: monotonic-X trace avoids O(n) minX rescans per sample BasicStroke stroke = ((BasicStroke)trace.getStroke()); - BasicStroke newStroke = new BasicStroke(DEFAULT_LINE_THICKNESS,stroke.getEndCap(),stroke.getLineJoin(),stroke.getMiterLimit(),stroke.getDashArray(),stroke.getDashPhase()); + BasicStroke newStroke = new BasicStroke(mTraceLineThickness,stroke.getEndCap(),stroke.getLineJoin(),stroke.getMiterLimit(),stroke.getDashArray(),stroke.getDashPhase()); trace.setStroke(newStroke); return trace; } @@ -412,7 +442,9 @@ public Chart2D getChart(){ * @param chart the Chart to be cleared */ public void removeAllSignals(){ + stopLiveViewportFrameClock(); //DEV-896: also the frame-close path (InternalFrameWithPlotManager.frameClosed()) mCurrentXValue=0; + mFrameClockNewestX=0; //DEV-896 super.removeAllSignals(); if (mChart!=null){ try { @@ -539,6 +571,10 @@ public void setXAxisRange(double minX,double maxY){ x.setRangePolicy(new RangePolicyFixedViewport(new Range(minX, maxY))); } + /** Anchors the X window's right edge to the newest plotted sample. Allocates a new range policy + * per call, so it is for explicit, occasional callers (window change, pause, static contents). + * Live time-axis plots should use the frame clock instead of calling this per sample - see + * {@link #setLiveViewportFrameClockEnabled(boolean)} (DEV-896). */ public void setXAxisRangeBasedOnXDuration(){ setXAxisRange(mCurrentXValue-(mXAxisTimeDuration*1000), mCurrentXValue); } @@ -553,6 +589,499 @@ public void setXAxisRangeBasedOnXDurationSubtractSingleSamplingRate(double sampl setXAxisRange(minTime, mCurrentXValue); } + //---------------------- DEV-896: live X viewport frame clock START -----------------------// + // + // Live time-axis plots used to move the X window from the data thread, once per sample: the + // window's right edge was the newest sample's X, so it advanced in whatever bursts the data + // arrived in (Bluetooth delivers 10-30 samples at once), and Chart2D's own 50 ms repaint timer + // then showed those bursts as 20 fps jumps. Here one Swing Timer per plot manager moves the + // window instead, on the EDT, by the real time elapsed since the previous frame, and repaints + // the chart right after, so every frame shows exactly one even step. + // + // The window trails the newest data by VIEWPORT_LATENCY_MS (a playout delay). It is NOT + // anchored to System.currentTimeMillis(): the time axis plots System_Timestamp_Plot, which is + // the device's own clock offset once, at the first packet, onto the PC epoch (see + // SystemTimestampPlot / SensorShimmerClock). So it is epoch ms, but it carries that first + // packet's latency and drifts with the device crystal (20 ppm is 72 ms per hour), and the PC + // clock can be stepped by NTP. Instead the right edge is a playout clock that advances with + // System.nanoTime() and is steered gently toward "newest X + time since it arrived - latency", + // which needs no common epoch, follows drift, and cannot jump with the wall clock. + // + // Threading: the data thread only writes mCurrentXValue and the frame-clock volatiles + // and, when the clock is not running, posts one start request to the EDT. Everything else runs + // on the EDT. The tick never takes the mListofPropertiestoPlot or mListofTraces monitors; it + // only takes the chart monitor (through jchart2d's property-change and repaint-flag methods), + // so it cannot invert the list -> chart lock order that filterDataAndPlot() relies on. + // + // Lifecycle (DEV-895/DEV-717: an idle app must not tick at 60 fps): the timer runs only while + // live time-axis samples are arriving into a chart that is showing. It stops itself on the + // first tick at which no sample has arrived for FRAME_CLOCK_IDLE_STOP_MS, the plot is paused, + // the chart is not showing (tab switched, frame iconified or closed), the X axis is not the + // time axis, or the data was cleared (mFrameClockNewestX back to 0, which removeAllSignals() and + // clearAllDataBuffer() do). removeAllSignals() - which InternalFrameWithPlotManager.frameClosed() + // calls - also stops it immediately. A stopped javax.swing.Timer is no longer referenced by + // Swing's TimerQueue, so it cannot pin this manager, its chart or the owning frame. + + /** Frame clock period: one X-window update and one chart repaint per tick, ~60 fps. If 60 fps + * proves too heavy for the EDT at UHD with many plots open, 33 (~30 fps) is the fallback; the + * motion stays time-correct at any rate because each tick advances by the real elapsed time. */ + public static final int FRAME_INTERVAL_MS = 16; + /** Playout delay: the live window's right edge trails "newest sample's X + time since it + * arrived" by this much. It absorbs Bluetooth bursts and the IOThread -> callback deque -> + * plot-thread hops, so data scrolls in evenly instead of in jumps; a sample becomes visible + * roughly this long after it was plotted. */ + public static final double VIEWPORT_LATENCY_MS = 200; + /** The frame clock stops once no live sample has arrived for this long. */ + public static final long FRAME_CLOCK_IDLE_STOP_MS = 2000; + /** Beyond this distance from its target the playout clock snaps instead of slewing: on the + * first tick, after a long stall, or when the X values jump (new session, clock reset). */ + private static final double FRAME_CLOCK_RESYNC_MS = 1000; + /** Extra history a live trace needs while the frame clock runs. A trace sized to exactly the + * window would leave a blank strip at the window's left edge, because the window trails the + * newest sample: by ~VIEWPORT_LATENCY_MS in steady running, but by up to + * FRAME_CLOCK_RESYNC_MS + VIEWPORT_LATENCY_MS while it catches up (at <=2x) after a data stall + * just short of the resync threshold - a longer stall snaps instead. The margin covers that + * worst case. See getLiveViewportTraceMarginInSeconds(). */ + public static final double LIVE_VIEWPORT_TRACE_MARGIN_MS = FRAME_CLOCK_RESYNC_MS + VIEWPORT_LATENCY_MS; + /** Share of the remaining error the playout clock corrects per tick (~0.3 s time constant). */ + private static final double FRAME_CLOCK_CORRECTION_GAIN = 0.05; + /** Largest correction per tick, as a share of that tick's elapsed time, for small errors and + * for slowing down: in normal running a frame's X step stays within +-10% of real time. */ + private static final double FRAME_CLOCK_MAX_SLEW = 0.1; + /** Largest speed-up per tick, as a share of the tick's elapsed time, once the window is behind + * its target by FRAME_CLOCK_CATCH_UP_FULL_MS or more (after a stall or a forward X jump below + * the snap threshold): the window then scrolls at up to 2x real time, so it recovers in about + * a second instead of the several seconds the 10% cap would take, and before the lag outgrows + * the trace margin. */ + private static final double FRAME_CLOCK_CATCH_UP_SLEW = 1.0; + /** Behind by less than this, only FRAME_CLOCK_MAX_SLEW applies: covers normal burst jitter. */ + private static final double FRAME_CLOCK_CATCH_UP_START_MS = 50; + /** Behind by this much or more, the full FRAME_CLOCK_CATCH_UP_SLEW applies; linear in between. */ + private static final double FRAME_CLOCK_CATCH_UP_FULL_MS = VIEWPORT_LATENCY_MS; + /** Share of the remaining error corrected per tick while catching up. */ + private static final double FRAME_CLOCK_CATCH_UP_GAIN = 0.15; + + // Anchored fallback. The playout clock assumes X advances about 1 ms per wall-clock ms and + // that new X arrives well within VIEWPORT_LATENCY_MS. Neither holds for Consensys DB playback + // (PlaybackSession replays at ~1.3x at "x1", because its timer period is truncated, and 2-4x+ + // at x2/x4) or for low-rate series (e.g. the 2 Hz fusion-response plot): the clock would then + // snap forward repeatedly, or freeze and rubber-band. So, from the arrivals of the newest X, + // the clock estimates the X rate and the spacing between new X values over windows of at + // least FRAME_CLOCK_RATE_WINDOW_MS, and when either is out of range - in the window itself and + // in its EWMA - for FRAME_CLOCK_MODE_SWITCH_WINDOWS windows in a row it switches to anchored mode: each tick the + // window's right edge is simply the newest X (the old behaviour, but still one update and one + // paint per tick). It switches back, with hysteresis, the same way. + /** Minimum span of newest-X arrivals per rate/spacing estimate. */ + private static final long FRAME_CLOCK_RATE_WINDOW_MS = 500; + /** EWMA weight of each new window's rate and spacing. */ + private static final double FRAME_CLOCK_RATE_EWMA_ALPHA = 0.5; + /** Consecutive windows a mode switch must be wanted for (a one-off X jump or a stall changes + * one window only). */ + private static final int FRAME_CLOCK_MODE_SWITCH_WINDOWS = 2; + /** Anchor when the X rate (X ms per wall-clock ms) is above / below these. */ + private static final double FRAME_CLOCK_ANCHOR_RATE_HIGH = 1.5; + private static final double FRAME_CLOCK_ANCHOR_RATE_LOW = 0.67; + /** Leave anchored mode only when the rate is back between these. */ + private static final double FRAME_CLOCK_UNANCHOR_RATE_HIGH = 1.2; + private static final double FRAME_CLOCK_UNANCHOR_RATE_LOW = 0.83; + /** Anchor when new X values arrive further apart than this. Above VIEWPORT_LATENCY_MS the + * playout clock rubber-bands (freezes at the newest sample, then catches up); at or just below + * it, e.g. a 5 Hz series, it still scrolls evenly, so the threshold is 1.2x the latency rather + * than below it. */ + private static final double FRAME_CLOCK_ANCHOR_SPACING_MS = 1.2*VIEWPORT_LATENCY_MS; + /** Leave anchored mode only when new X values arrive closer together than this. */ + private static final double FRAME_CLOCK_UNANCHOR_SPACING_MS = 0.75*VIEWPORT_LATENCY_MS; + /** Anchored because X runs fast (playback): the right edge may advance at most this many times + * the estimated X rate per tick, so two deliveries landing in one tick (e.g. a 15.6 ms playback + * timer against 16 ms frames) are spread over the next frames instead of showing as one double + * step. Anchored for sparse data at ~1x rate, the edge jumps straight to the newest X. */ + private static final double FRAME_CLOCK_ANCHORED_MAX_SPEED_FACTOR = 1.5; + /** Chart2D's own repaint timer delay while the frame clock repaints the chart itself. Kept long + * so that timer does not add a second, unsynchronised stream of paints; restored on stop. */ + private static final int FRAME_CLOCK_CHART_PAINT_LATENCY_MS = 250; + /** At most one start request per this interval from the data thread. */ + private static final long FRAME_CLOCK_START_REQUEST_MIN_INTERVAL_NS = 100L*1000*1000; + + private volatile boolean mIsLiveViewportFrameClockEnabled = false; + /** System.nanoTime() when the data thread last moved mCurrentXValue (any device). Used for + * idle detection. Data thread writes. */ + private volatile long mLastLiveSampleNanos = 0; + /** Newest X seen by the frame clock, 0 = none since the last clear. Unlike mCurrentXValue, + * which alternates between devices' timestamps in a multi-device plot, this only moves + * forward, except on a genuine backward jump (reconnect, device reset): X more than + * FRAME_CLOCK_RESYNC_MS behind it, with nothing closer arriving for + * FRAME_CLOCK_BACKWARD_JUMP_CONFIRM_MS. Data thread writes (before mFrameClockNewestXNanos). */ + private volatile double mFrameClockNewestX = 0; + /** System.nanoTime() when mFrameClockNewestX was last moved. */ + private volatile long mFrameClockNewestXNanos = 0; + /** Data thread only: System.nanoTime() of the last sample within FRAME_CLOCK_RESYNC_MS of + * mFrameClockNewestX. */ + private long mFrameClockLastNearNewestNanos = 0; + /** A sample far behind the newest X only counts as a backward jump once no sample near the + * newest X has arrived for this long. Without it, two devices whose timestamps differ by more + * than FRAME_CLOCK_RESYNC_MS would reset the newest X on every sample of the slower one. */ + private static final long FRAME_CLOCK_BACKWARD_JUMP_CONFIRM_MS = 500; + private volatile javax.swing.Timer mFrameClockTimer = null; + /** Written on the EDT only; read by the data thread to decide whether to request a start. */ + private volatile boolean mIsFrameClockRunning = false; + private final AtomicBoolean mIsFrameClockStartPending = new AtomicBoolean(false); + /** Data thread only. */ + private long mLastFrameClockStartRequestNanos = System.nanoTime() - FRAME_CLOCK_START_REQUEST_MIN_INTERVAL_NS; + //EDT-only state below + private double mFrameClockViewportEndX = Double.NaN; + /** Anchored fallback state (see FRAME_CLOCK_ANCHOR_*). */ + private boolean mIsFrameClockAnchored = false; + /** Just left anchored mode: hold the window still until the playout target catches up with it, + * instead of stepping back by up to VIEWPORT_LATENCY_MS. */ + private boolean mIsFrameClockHoldingAfterAnchor = false; + private boolean mIsFrameClockRateBaseSet = false; + private double mFrameClockRateBaseX = 0; + private long mFrameClockRateBaseNanos = 0; + private long mFrameClockRateLastSeenNanos = 0; + private int mFrameClockRateUpdatesInWindow = 0; + private double mFrameClockRateEwma = Double.NaN; + private double mFrameClockSpacingEwmaMs = Double.NaN; + private int mFrameClockModeSwitchVotes = 0; + private long mLastFrameClockTickNanos = 0; + private Chart2D mFrameClockChart = null; + private int mFrameClockSavedPaintLatency = -1; + /** Installed on the X axis once, then only its Range is swapped per tick (no per-frame policy + * allocation). Replaced only if something else installed a different policy in between. */ + private RangePolicyFixedViewport mFrameClockRangePolicy = null; + private Range mFrameClockSpareRange = null; + + /** Lets a frame clock, rather than each incoming sample, move this plot's X window while the X + * axis is the time axis. Enable it before signals are added, so callers that size traces from + * {@link #getLiveViewportTraceMarginInSeconds()} see the margin. Non-time X axes (frequency/FFT, + * value) are unaffected: the clock never runs for them. */ + public void setLiveViewportFrameClockEnabled(boolean enabled){ + mIsLiveViewportFrameClockEnabled = enabled; + if(!enabled){ + stopLiveViewportFrameClock(); + } + } + + public boolean isLiveViewportFrameClockEnabled(){ + return mIsLiveViewportFrameClockEnabled; + } + + public boolean isLiveViewportFrameClockRunning(){ + return mIsFrameClockRunning; + } + + /** Extra seconds of history a live trace should hold beyond the X window, 0 when the frame + * clock is disabled. */ + public double getLiveViewportTraceMarginInSeconds(){ + return mIsLiveViewportFrameClockEnabled ? (LIVE_VIEWPORT_TRACE_MARGIN_MS/1000.0) : 0; + } + + /** Stops the frame clock now; it restarts by itself when live samples arrive again. Safe from + * any thread: off the EDT the timer is stopped directly (javax.swing.Timer.stop() is + * thread-safe) and the rest of the teardown, which touches the chart, is posted to the EDT. */ + public void stopLiveViewportFrameClock(){ + if(SwingUtilities.isEventDispatchThread()){ + stopFrameClockOnEdt(false); + } + else{ + javax.swing.Timer timer = mFrameClockTimer; + if(timer!=null){ + timer.stop(); + } + SwingUtilities.invokeLater(new Runnable(){ + @Override + public void run() { + stopFrameClockOnEdt(false); + } + }); + } + } + + /** Data thread, once per sample that moved mCurrentXValue on a time X axis. Cheap on purpose: + * a nanoTime() read, a few volatile accesses and, only while the clock is stopped, a throttled + * check. */ + private void noteLiveSampleForFrameClock(double xData){ + long nowNanos = System.nanoTime(); + mLastLiveSampleNanos = nowNanos; + updateFrameClockNewestX(xData, nowNanos); + if(!mIsFrameClockRunning + && (nowNanos-mLastFrameClockStartRequestNanos) >= FRAME_CLOCK_START_REQUEST_MIN_INTERVAL_NS){ + Chart2D chart = mChart; + //isShowing() off the EDT is a benign racy read: at worst one request is skipped or wasted. + //Checking it here keeps a hidden plot from posting a start request per sample. + if(chart!=null && isChartDisplayed(chart) && mIsFrameClockStartPending.compareAndSet(false, true)){ + mLastFrameClockStartRequestNanos = nowNanos; + SwingUtilities.invokeLater(new Runnable(){ + @Override + public void run() { + startFrameClockOnEdt(); + } + }); + } + } + } + + /** Data thread (or a test). Keeps mFrameClockNewestX = max(X seen), restarting from xData on a + * genuine backward jump (see mFrameClockNewestX). */ + void updateFrameClockNewestX(double xData, long nowNanos){ + double newest = mFrameClockNewestX; + boolean isNearNewest = xData>=newest-FRAME_CLOCK_RESYNC_MS; + if(newest==0 || xData>newest + || (!isNearNewest && (nowNanos-mFrameClockLastNearNewestNanos) > FRAME_CLOCK_BACKWARD_JUMP_CONFIRM_MS*1000*1000)){ + mFrameClockNewestX = xData; + mFrameClockNewestXNanos = nowNanos; + mFrameClockLastNearNewestNanos = nowNanos; + } + else if(isNearNewest){ + mFrameClockLastNearNewestNanos = nowNanos; + } + } + + /** Showing, and its top-level frame not iconified (an iconified JFrame's components still + * report isShowing()). Off the EDT this is a benign racy read. */ + private static boolean isChartDisplayed(Chart2D chart){ + if(!chart.isShowing()){ + return false; + } + java.awt.Window window = SwingUtilities.getWindowAncestor(chart); + return !(window instanceof java.awt.Frame) || (((java.awt.Frame)window).getExtendedState() & java.awt.Frame.ICONIFIED)==0; + } + + private boolean isFrameClockWanted(){ + return mIsLiveViewportFrameClockEnabled && isXAxisTime() && !mIsPlotPaused && mFrameClockNewestX!=0; + } + + /** EDT. */ + private void startFrameClockOnEdt(){ + mIsFrameClockStartPending.set(false); + Chart2D chart = mChart; + if(mIsFrameClockRunning || !isFrameClockWanted() || chart==null || !isChartDisplayed(chart)){ + return; + } + if(mFrameClockTimer==null){ + javax.swing.Timer timer = new javax.swing.Timer(FRAME_INTERVAL_MS, new java.awt.event.ActionListener(){ + @Override + public void actionPerformed(java.awt.event.ActionEvent e) { + onFrameClockTick(); + } + }); + timer.setCoalesce(true); + mFrameClockTimer = timer; + } + mFrameClockViewportEndX = Double.NaN; + mFrameClockChart = chart; + mFrameClockSavedPaintLatency = chart.getMinPaintLatency(); + chart.setMinPaintLatency(FRAME_CLOCK_CHART_PAINT_LATENCY_MS); + mIsFrameClockRunning = true; + mFrameClockTimer.start(); + //Apply a current window now rather than one timer interval later, so a chart that was just + //shown again does not paint its stale window for the first frames. + onFrameClockTick(); + } + + /** EDT. + * @param snapToNewestSample leave the window ending at the newest sample, as the old + * sample-driven path did, so nothing received stays hidden behind the playout delay. */ + private void stopFrameClockOnEdt(boolean snapToNewestSample){ + javax.swing.Timer timer = mFrameClockTimer; + if(timer!=null){ + timer.stop(); + } + boolean wasRunning = mIsFrameClockRunning; + mIsFrameClockRunning = false; + mFrameClockViewportEndX = Double.NaN; + resetFrameClockRateEstimate(); + Chart2D chart = mFrameClockChart; + mFrameClockChart = null; + if(chart!=null && mFrameClockSavedPaintLatency>0){ + chart.setMinPaintLatency(mFrameClockSavedPaintLatency); + } + mFrameClockSavedPaintLatency = -1; + + double latestX = mFrameClockNewestX; + if(wasRunning && snapToNewestSample && chart!=null && chart==mChart && latestX!=0){ + applyLiveViewport(chart, latestX-(mXAxisTimeDuration*1000), latestX); + chart.repaint(); + } + } + + /** EDT, once per FRAME_INTERVAL_MS while the clock runs. */ + private void onFrameClockTick(){ + if(!mIsFrameClockRunning){ + return; //an event already queued when the timer was stopped + } + Chart2D chart = mChart; + if(!isXAxisTime()){ + stopFrameClockOnEdt(false); //do not put a time window on a value/frequency axis + return; + } + if(chart==null || chart!=mFrameClockChart || !mIsLiveViewportFrameClockEnabled || !isChartDisplayed(chart)){ + stopFrameClockOnEdt(true); + return; + } + //Read the arrival time before X: the data thread writes X first, so a fresh arrival time + //implies a fresh X. + long newestXNanos = mFrameClockNewestXNanos; + double newestX = mFrameClockNewestX; + if(newestX==0){ + stopFrameClockOnEdt(false); //cleared: leave the axis to whoever cleared it + return; + } + long nowNanos = System.nanoTime(); + if(mIsPlotPaused || (nowNanos-mLastLiveSampleNanos) > FRAME_CLOCK_IDLE_STOP_MS*1000*1000){ + stopFrameClockOnEdt(true); + return; + } + double end = computeLiveViewportEnd(nowNanos, newestX, newestXNanos); + applyLiveViewport(chart, end-(mXAxisTimeDuration*1000), end); + //This tick paints the chart itself, now, so each frame shows exactly one step. Clearing + //the flag stops Chart2D's own timer from scheduling a second paint for the same changes. + chart.setRequestedRepaint(false); + chart.repaint(); + } + + /** EDT (or a test driving it directly). Advances the playout clock to nowNanos and returns the + * X window's new right edge. + * @param latestX newest X plotted (mFrameClockNewestX) + * @param lastSampleNanos System.nanoTime() when that X was plotted */ + double computeLiveViewportEnd(long nowNanos, double latestX, long lastSampleNanos){ + updateFrameClockRateEstimate(latestX, lastSampleNanos); + double sinceSampleMs = (nowNanos-lastSampleNanos)/1e6; + double target = latestX + sinceSampleMs - VIEWPORT_LATENCY_MS; + double previousEnd = mFrameClockViewportEndX; + double end; + if(mIsFrameClockAnchored){ + //X does not advance like wall-clock time, or arrives too sparsely: follow it directly. + end = latestX; + if(!Double.isNaN(previousEnd) && mFrameClockRateEwma>FRAME_CLOCK_UNANCHOR_RATE_HIGH + && latestX>=previousEnd && latestX-previousEnd<=FRAME_CLOCK_RESYNC_MS){ + double frameMs = Math.max(0, (nowNanos-mLastFrameClockTickNanos)/1e6); + end = Math.min(latestX, previousEnd + frameMs*mFrameClockRateEwma*FRAME_CLOCK_ANCHORED_MAX_SPEED_FACTOR); + } + mIsFrameClockHoldingAfterAnchor = true; + } + else if(Double.isNaN(previousEnd) || Math.abs(target-previousEnd) > FRAME_CLOCK_RESYNC_MS){ + end = Math.min(target, latestX); + mIsFrameClockHoldingAfterAnchor = false; + } + else if(mIsFrameClockHoldingAfterAnchor && target=FRAME_CLOCK_MODE_SWITCH_WINDOWS){ + mIsFrameClockAnchored = !mIsFrameClockAnchored; + mFrameClockModeSwitchVotes = 0; + } + } + + private static boolean isFrameClockRateAbnormal(double rate, double spacingMs){ + return rate>FRAME_CLOCK_ANCHOR_RATE_HIGH || rateFRAME_CLOCK_ANCHOR_SPACING_MS; + } + + private static boolean isFrameClockRateNormal(double rate, double spacingMs){ + return rate>=FRAME_CLOCK_UNANCHOR_RATE_LOW && rate<=FRAME_CLOCK_UNANCHOR_RATE_HIGH && spacingMs axisX = chart.getAxisX(); + if(mFrameClockRangePolicy==null || axisX.getRangePolicy()!=mFrameClockRangePolicy){ + mFrameClockRangePolicy = new RangePolicyFixedViewport(new Range(minX, maxX)); + mFrameClockSpareRange = new Range(minX, maxX); + axisX.setRangePolicy(mFrameClockRangePolicy); + return; + } + Range spare = mFrameClockSpareRange; + mFrameClockSpareRange = mFrameClockRangePolicy.getRange(); + spare.setMin(minX); + spare.setMax(maxX); + mFrameClockRangePolicy.setRange(spare); + } + + //---------------------- DEV-896: live X viewport frame clock END -----------------------// + public void setYAxisRange(double miny,double maxy){ IAxis yAxisLeft = mChart.getAxisY(); yAxisLeft.setRangePolicy(new RangePolicyFixedViewport(new Range(miny, maxy))); @@ -940,7 +1469,7 @@ public void setTraceLineStyle(ITrace2D trace, PLOT_LINE_STYLE selectedLineStyle) || selectedLineStyle==PLOT_LINE_STYLE.INDIVIDUAL_POINTS){ strokeNew = new BasicStroke( // strokeOld.getLineWidth(), - DEFAULT_LINE_THICKNESS, + mTraceLineThickness, //DEV-896: was DEFAULT_LINE_THICKNESS strokeOld.getEndCap(), strokeOld.getLineJoin(), strokeOld.getMiterLimit(), @@ -1520,6 +2049,7 @@ public synchronized void clearAllDataBuffer(){ } setXAxisDuration(mXAxisTimeDuration); mCurrentXValue=0; + mFrameClockNewestX=0; //DEV-896 isFirstPointOnFillTrace=true; } @@ -2173,6 +2703,9 @@ public void filterDataAndPlot(ObjectCluster ojc) throws Exception { //DEV-896: stash rather than propagate, so the deferred work still gets replayed on the //"Trace does not exist" path (it used to run inline, before the batching). Exception pendingException = null; + //DEV-896: whether this sample moved mCurrentXValue, i.e. is live data for the frame clock. + boolean isCurrentXValueUpdated = false; + double xDataForFrameClock = 0; try { while (entries.hasNext()) { synchronized(chartMonitor){ @@ -2260,6 +2793,8 @@ public void filterDataAndPlot(ObjectCluster ojc) throws Exception { } mCurrentXValue = xData; + isCurrentXValueUpdated = true; + xDataForFrameClock = xData; //DEV-896: record instead of printing/updating Swing here - see DeferredPlotAction. //The trace size is read now, under the monitor, so the deferred debug line @@ -2347,6 +2882,12 @@ else if(isXAxisFrequency){ if(isDummyPointAddedToFillTrace) { isFirstPointOnFillTrace = false; } + + //DEV-896: the frame clock, not this per-sample path, moves the X window of a live + //time-axis plot (see setLiveViewportFrameClockEnabled()). + if(isCurrentXValueUpdated && isXAxisTime && mIsLiveViewportFrameClockEnabled){ + noteLiveSampleForFrameClock(xDataForFrameClock); + } } } // mChart.getAxisX().setRange(new Range(mCurrentXValue-(mXAxisTimeDuraton*1000),mCurrentXValue)); diff --git a/ShimmerDriverPC/src/main/java/com/shimmerresearch/pcDriver/ShimmerGRPC.java b/ShimmerDriverPC/src/main/java/com/shimmerresearch/pcDriver/ShimmerGRPC.java index f9dc48001..0f251cc73 100644 --- a/ShimmerDriverPC/src/main/java/com/shimmerresearch/pcDriver/ShimmerGRPC.java +++ b/ShimmerDriverPC/src/main/java/com/shimmerresearch/pcDriver/ShimmerGRPC.java @@ -290,10 +290,21 @@ protected void writeBytes(byte[] data) { // Remote gRPC service is not available, so disconnect Shimmer device sre.printStackTrace(); System.out.println("ERROR: Lost connection to GRPC Server"); - connectionLost(); + if(!isOnStoppedIoThread()){ + connectionLost(); + } } } + /** DEV-895: true when running on an IOThread whose stop flag is set, i.e. the failure is the + * expected consequence of closeConnection() tearing down under an IOThread that outlived the + * bounded join. Reporting CONNECTION_LOST then would turn a user disconnect into an + * auto-reconnect downstream. */ + private boolean isOnStoppedIoThread(){ + Thread t = Thread.currentThread(); + return (t instanceof IOThread) && ((IOThread)t).stop; + } + @Override protected void stop() { // TODO Auto-generated method stub @@ -541,17 +552,62 @@ public void disconnect() throws ShimmerException { private void closeConnection() { try { - if (mIOThread != null) { - mIOThread.stop = true; - mIOThread.interrupt(); - mIOThread.join(); // Wait until the thread terminates - mIOThread = null; - - if (mUseProcessingThread) { - mPThread.stop = true; - mPThread.interrupt(); - mPThread.join(); - mPThread = null; + // closeConnection() is unsynchronized and can be entered concurrently - once from + // connectionLost() running on the IOThread itself, and once from a user-triggered + // disconnect() on another thread. Snapshot the fields into locals before touching + // them so a concurrent caller nulling the field out mid-method can't turn a passed + // null-check into an NPE further down (see ShimmerPC.closeConnection() for the + // same fix). + IOThread ioThread = mIOThread; + if (ioThread != null) { + ioThread.stop = true; + // Skip the join when closeConnection() is reached from the IOThread itself - + // a self-join can never succeed and would just burn the full timeout. The + // interrupt() call moves inside this guard too: calling it unconditionally + // would mark the *current* thread interrupted in the self-close case. + if (Thread.currentThread() != ioThread) { + // Interrupt before joining: run() now exits promptly on + // Thread.currentThread().isInterrupted(), and any idle Thread.sleep() + // it's waiting in will wake immediately - making shutdown faster and + // more deterministic than waiting out the bounded join first. + ioThread.interrupt(); + try { + ioThread.join(2000); // Bounded wait so this can't block indefinitely + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + if (ioThread.isAlive()) { + // Still not terminated after the interrupt + bounded join. + consolePrintLn("Warning: IOThread did not terminate within join timeout"); + } + } + // Only clear the field if it still refers to the thread we stopped, so a + // late closeConnection() cannot clobber a reconnect's new IOThread. + if (mIOThread == ioThread) { + mIOThread = null; + } + } + // Not nested under the IOThread block: a concurrent caller may already have + // nulled mIOThread while the ProcessingThread is still running. + if (mUseProcessingThread) { + ProcessingThread pThread = mPThread; + if (pThread != null) { + pThread.stop = true; + if (Thread.currentThread() != pThread) { + // Interrupt before joining - see the IOThread teardown above. + pThread.interrupt(); + try { + pThread.join(2000); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + if (pThread.isAlive()) { + consolePrintLn("Warning: ProcessingThread did not terminate within join timeout"); + } + } + if (mPThread == pThread) { + mPThread = null; + } } } mIsStreaming = false; @@ -561,7 +617,7 @@ private void closeConnection() { } catch (Exception ex) { consolePrintException(ex.getMessage(), ex.getStackTrace()); setBluetoothRadioState(BT_STATE.DISCONNECTED); - } + } } //Need to override here because ShimmerDevice class uses a different map diff --git a/ShimmerDriverPC/src/main/java/com/shimmerresearch/pcDriver/ShimmerPC.java b/ShimmerDriverPC/src/main/java/com/shimmerresearch/pcDriver/ShimmerPC.java index eda410989..bd30f78ad 100644 --- a/ShimmerDriverPC/src/main/java/com/shimmerresearch/pcDriver/ShimmerPC.java +++ b/ShimmerDriverPC/src/main/java/com/shimmerresearch/pcDriver/ShimmerPC.java @@ -434,7 +434,9 @@ public boolean bytesAvailableToBeRead() { } catch (SerialPortException | NullPointerException ex) { consolePrintException(ex.getMessage(), ex.getStackTrace()); - connectionLost(); + if(!isOnStoppedIoThread()){ + connectionLost(); + } // e.printStackTrace(); } return false; @@ -450,7 +452,9 @@ public int availableBytes(){ } } catch (SerialPortException | NullPointerException ex) { consolePrintException(ex.getMessage(), ex.getStackTrace()); - connectionLost(); + if(!isOnStoppedIoThread()){ + connectionLost(); + } return 0; } } @@ -467,7 +471,9 @@ public void writeBytes(byte[] data) { } catch (SerialPortException | NullPointerException ex) { consolePrintLn("Tried to writeBytes but port is closed"); consolePrintException(ex.getMessage(), ex.getStackTrace()); - connectionLost(); + if(!isOnStoppedIoThread()){ + connectionLost(); + } } } @@ -491,7 +497,9 @@ protected byte[] readBytes(int numberOfBytes) { } } } catch (SerialPortException | NullPointerException e) { - connectionLost(); + if(!isOnStoppedIoThread()){ + connectionLost(); + } consolePrintLn("Tried to readBytes but serial port error"); consolePrintException(e.getMessage(), e.getStackTrace()); // e.printStackTrace(); @@ -505,7 +513,9 @@ protected byte[] readBytes(int numberOfBytes) { // ShimmerBluetooth if(mBluetoothRadioState==BT_STATE.CONNECTING || mBluetoothRadioState==BT_STATE.CONFIGURING){ - connectionLost(); + if(!isOnStoppedIoThread()){ + connectionLost(); + } } } return null; @@ -595,6 +605,15 @@ public void disconnectNoException() { } } + /** DEV-895: true when running on an IOThread whose stop flag is set, i.e. the failure is the + * expected consequence of closeConnection() closing the port under a reader that outlived the + * bounded join. Reporting CONNECTION_LOST then would turn a user disconnect into an + * auto-reconnect downstream. */ + private boolean isOnStoppedIoThread(){ + Thread t = Thread.currentThread(); + return (t instanceof IOThread) && ((IOThread)t).stop; + } + @Override protected void connectionLost() { disconnectNoException(); @@ -605,17 +624,71 @@ protected void connectionLost() { private void closeConnection(){ try { - if (mIOThread != null) { - mIOThread.stop = true; - - // Closing serial port before before thread is finished stopping throws an error so waiting here - while(mIOThread != null && mIOThread.isAlive()); + // closeConnection() is unsynchronized and can be entered concurrently - + // once from connectionLost() running on the IOThread itself, and once from + // a user-triggered disconnect() on another thread. Snapshot the fields into + // locals before touching them so a concurrent caller nulling the field out + // mid-method can't turn a passed null-check into an NPE further down (which + // would otherwise be swallowed by the catch below and skip purgePort/closePort, + // leaking the COM port). + IOThread ioThread = mIOThread; + if (ioThread != null) { + ioThread.stop = true; + + // Closing serial port before thread is finished stopping throws an error so waiting here. + // Bounded join instead of an empty-body busy-wait, so this can't block indefinitely. + // Skip the join when closeConnection() is reached from the IOThread itself + // (connectionLost() fires on it when the serial port errors mid-read/write) - + // a self-join can never succeed and would just burn the full timeout. + if(Thread.currentThread() != ioThread){ + // Interrupt before joining: run() now exits promptly on + // Thread.currentThread().isInterrupted(), and any idle Thread.sleep() + // it's waiting in will wake immediately - making shutdown faster and + // more deterministic than waiting out the bounded join first. + ioThread.interrupt(); + try { + ioThread.join(2000); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + if (ioThread.isAlive()) { + // Still not terminated after the interrupt + bounded join - most + // likely blocked in a non-interruptible native serial read. Just + // warn; a second interrupt() here wouldn't unblock it either. + consolePrintLn("Warning: IOThread did not terminate within join timeout; it may be blocked in a non-interruptible read"); + } + } - mIOThread = null; - - if(mUseProcessingThread){ - mPThread.stop = true; - mPThread = null; + // Only clear the field if it still refers to the thread we stopped, so a + // late closeConnection() cannot clobber a reconnect's new IOThread. + if (mIOThread == ioThread) { + mIOThread = null; + } + } + // Not nested under the IOThread block: a concurrent caller may already have + // nulled mIOThread while the ProcessingThread is still running. + if(mUseProcessingThread){ + ProcessingThread pThread = mPThread; + if (pThread != null) { + pThread.stop = true; + // buildAndSendMsg() runs on the ProcessingThread and dispatches to app + // listeners, so a listener calling disconnect() would self-join here - + // guard the same way as the IOThread above. + if (Thread.currentThread() != pThread) { + // Interrupt before joining - see the IOThread teardown above. + pThread.interrupt(); + try { + pThread.join(2000); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + if (pThread.isAlive()) { + consolePrintLn("Warning: ProcessingThread did not terminate within join timeout"); + } + } + if (mPThread == pThread) { + mPThread = null; + } } } mIsStreaming = false; @@ -827,8 +900,13 @@ else if(isSDLogging()){ } else{ // if(!isStreaming() && !isSDLogging() && isConnected()){ - if(!mIsStreaming && !isSDLogging() && isConnected() && mBluetoothRadioState!=BT_STATE.CONNECTED){ - setBluetoothRadioState(BT_STATE.CONNECTED); + // While connecting, the connect sequence's own end (inquiryDone(), then + // isReadyForStreaming()) moves CONNECTING to CONNECTED. The sequence reads the + // status part way through, and if that reply did it, the app would be told the + // unit is ready while the rest of the sequence is still queued (DEV-1275). + if(!mIsStreaming && !isSDLogging() && isConnected() + && mBluetoothRadioState!=BT_STATE.CONNECTED && mBluetoothRadioState!=BT_STATE.CONNECTING){ + setBluetoothRadioState(BT_STATE.CONNECTED); } // if(getBTState() == BT_STATE.INITIALISED){ // diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00028_IoThreadTeardownTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00028_IoThreadTeardownTest.java new file mode 100644 index 000000000..18f44c653 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00028_IoThreadTeardownTest.java @@ -0,0 +1,193 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.lang.management.ManagementFactory; +import java.lang.management.ThreadMXBean; +import java.util.concurrent.ConcurrentLinkedDeque; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; + +import org.junit.After; +import org.junit.Assume; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunication; +import com.shimmerresearch.verisense.communication.ByteCommunicationListener; + +import jssc.SerialPortException; +import jssc.SerialPortTimeoutException; + +/** + * DEV-895: the IOThread and ProcessingThread must sleep rather than spin when + * idle, must stop promptly on disconnect(), and a disconnect() must stay a + * disconnect. closeConnection() only waits a bounded 2 s for the IOThread, so + * one blocked in a non-interruptible serial call outlives it, and the port is + * closed under it. When that call then fails, the I/O helpers used to report + * CONNECTION_LOST, which NeuroLynQ answers with an auto-reconnect. + *

+ * No hardware: the threads are started as connect() starts them, over an + * in-memory radio. It lives in this package because mIOThread and mPThread + * are protected members of ShimmerBluetooth. + */ +public class API_00028_IoThreadTeardownTest { + + /** Thread-safe in-memory radio. Its writes can block, ignoring interrupts, as a native jssc call does. */ + private static class BlockingRadio implements ByteCommunication { + final ConcurrentLinkedDeque rx = new ConcurrentLinkedDeque(); + final long writeBlockMs; + final CountDownLatch writeStarted = new CountDownLatch(1); + volatile boolean open = true; + + BlockingRadio(long writeBlockMs) { + this.writeBlockMs = writeBlockMs; + } + + @Override + public boolean writeBytes(byte[] buffer) throws SerialPortException { + writeStarted.countDown(); + if(writeBlockMs>0){ + long end = System.currentTimeMillis()+writeBlockMs; + boolean interrupted = false; + long left; + while((left = end-System.currentTimeMillis())>0){ + try { + Thread.sleep(left); + } catch (InterruptedException e) { + interrupted = true; + } + } + if(interrupted){ + Thread.currentThread().interrupt(); + } + if(!open){ + throw new SerialPortException("TEST", "writeBytes", "Port closed during write"); + } + } + return true; + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException, SerialPortException { + if(!open){ + throw new SerialPortException("TEST", "readBytes", "Port not opened"); + } + if(rx.size()0){ + Thread.sleep(left); + } + assertEquals("still disconnected, not CONNECTION_LOST", BT_STATE.DISCONNECTED, device.getBluetoothRadioState()); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00030_StreamingInstreamResponseQueueTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00030_StreamingInstreamResponseQueueTest.java new file mode 100644 index 000000000..1aba75222 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00030_StreamingInstreamResponseQueueTest.java @@ -0,0 +1,277 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayDeque; +import java.util.Arrays; +import java.util.Deque; + +import org.junit.After; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_CRC_MODE; +import com.shimmerresearch.comms.wiredProtocol.ShimmerCrc; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunication; +import com.shimmerresearch.verisense.communication.ByteCommunicationListener; + +import jssc.SerialPortTimeoutException; + +/** + * DEV-1262: while streaming, the branch of processPacket() for an in-stream + * response (FF 8A ...) completed the command in flight whatever the response + * was: it cancelled the ACK timer, cleared the wait flags, removed the head of + * the instruction queue and unlocked it. The firmware also sends a status + * response unprompted (dock, undock, the user button, a low-battery stop), so + * such a push removed a SET command that was still waiting for its ACK, or a + * queued instruction not yet sent, and the next ACK was matched to the wrong + * instruction. The protocol matches a response to the command in flight by + * its opcode (log-and-stream-common docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md + * section 5.4, rule 2). + *

+ * No hardware: the parser reads from an in-memory byte queue, one byte at a + * time as the IO thread does, as in API_00027. + */ +public class API_00030_StreamingInstreamResponseQueueTest { + + /** Bytes after the DATA_PACKET byte: a 3-byte timestamp and three 2-byte channels */ + private static final int PACKET_SIZE = 9; + + /** Docked, sensing, RTC set and streaming; not SD logging */ + private static final byte STATUS_DOCKED_AND_STREAMING = 0x17; + + private static class QueueRadio implements ByteCommunication { + final Deque rx = new ArrayDeque(); + + void queue(byte... bytes) { + for(byte b:bytes){ + rx.add(b); + } + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() + * The STOP stays at the head of the instruction list, in flight, until its stop handling retires it: + * the first byte after it (stream data, while streaming) starts that handling, which sleeps 400 ms, + * then removes the head of the list (removeInstruction(0)). A configuration's operationPrepare() + * clears the list, so inside that window it removed the STOP, the operation queued its chunks, and + * the stop handling then removed the first chunk in the STOP's place. + *

+ * No hardware: the IOThread runs as connect() starts it, over an in-memory radio that acknowledges + * every SET_INFOMEM as the firmware does. It lives in this package because mIOThread is a protected + * member of ShimmerBluetooth. + */ +public class API_00031_ConfigureStraightAfterStopTest { + + /** Three 128-byte chunks, as a Shimmer3 or Shimmer3R configuration is written */ + private static final int CONFIG_BYTES = 384; + + private static class AnsweringRadio implements ByteCommunication { + final ConcurrentLinkedDeque rx = new ConcurrentLinkedDeque(); + final List written = Collections.synchronizedList(new ArrayList()); + final CountDownLatch stopSent = new CountDownLatch(1); + + void queue(byte... bytes) { + for(byte b:bytes){ + rx.add(b); + } + } + + /** The address of each SET_INFOMEM written: [0x8C, length, address LSB, address MSB, data...] */ + List infoMemAddressesWritten() { + List addresses = new ArrayList(); + synchronized(written){ + for(byte[] w:written){ + if(w[0]==ShimmerObject.SET_INFOMEM_COMMAND){ + addresses.add((w[2]&0xFF) | ((w[3]&0xFF)<<8)); + } + } + } + return addresses; + } + + boolean wrote(byte command) { + synchronized(written){ + for(byte[] w:written){ + if(w[0]==command){ + return true; + } + } + } + return false; + } + + @Override + public boolean writeBytes(byte[] buffer) { + written.add(buffer.clone()); + if(buffer[0]==ShimmerObject.STOP_STREAMING_COMMAND){ + // Its reply is the test's to send, so the test controls when the stop handling starts + stopSent.countDown(); + } + else { + // Every other command here is a SET, which the firmware acknowledges + queue(ShimmerObject.ACK_COMMAND_PROCESSED); + } + return true; + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() waitForChunks(AnsweringRadio radio, int count, long timeoutMs) throws InterruptedException { + long end = System.currentTimeMillis()+timeoutMs; + while(radio.infoMemAddressesWritten().size() chunks = waitForChunks(radio, ALL_THREE_CHUNKS.length, 5000); + assertEquals("the SET_INFOMEM chunks sent, by address", java.util.Arrays.asList(ALL_THREE_CHUNKS), chunks); + } + + /** + * When the unit's ACK is the first byte after the STOP, with no data packet in flight, the stop + * handling retired the STOP and the same byte then went on as an ACK and retired the next + * instruction too: here a plain SET queued straight after stopStreaming(), with no configuration + * operation at all. + */ + @Test + public void aCommandQueuedAfterTheStopIsSentWhenTheAckComesFirst() throws Exception { + AnsweringRadio radio = streamingShimmer3r(); + mDevice.stopStreaming(); + mDevice.writeAccelRange(1); + assertTrue("the STOP was sent", radio.stopSent.await(2, TimeUnit.SECONDS)); + startStopHandling(radio, ShimmerObject.ACK_COMMAND_PROCESSED); + + long end = System.currentTimeMillis()+3000; + while(!radio.wrote(ShimmerObject.SET_ACCEL_SENSITIVITY_COMMAND) && System.currentTimeMillis() chunks = waitForChunks(radio, ALL_THREE_CHUNKS.length, 5000); + assertEquals("the SET_INFOMEM chunks sent, by address", java.util.Arrays.asList(ALL_THREE_CHUNKS), chunks); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00032_StreamingAckAfterPauseTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00032_StreamingAckAfterPauseTest.java new file mode 100644 index 000000000..69f5e4e5d --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00032_StreamingAckAfterPauseTest.java @@ -0,0 +1,302 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Deque; +import java.util.List; + +import org.junit.After; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_CRC_MODE; +import com.shimmerresearch.comms.wiredProtocol.ShimmerCrc; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.driverUtilities.UtilShimmer; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunication; +import com.shimmerresearch.verisense.communication.ByteCommunicationListener; + +import jssc.SerialPortTimeoutException; + +/** + * DEV-1291: after STOP_LOGGING_ONLY_COMMAND the unit stops sending data packets + * for about 100 ms while it closes its SD file. A command sent in that pause is + * answered at once, so its ACK comes straight after the previous ACK's CRC with + * no data packet before it. processPacket() only looks for an ACK after a data + * packet, so it threw the reply away; the command timed out, and the timeout + * dropped every instruction queued behind it. Both a Shimmer3 and a Shimmer3R do + * it (found by the Java HIL, DEV-1269). + *

+ * Only with a link CRC: without one the previous ACK isn't processed until the + * stream resumes, so the next command never goes out during the pause. + *

+ * No hardware: the parser reads from an in-memory byte queue, one byte at a + * time as the IO thread does, as in API_00027 and API_00030. + */ +public class API_00032_StreamingAckAfterPauseTest { + + /** Bytes after the DATA_PACKET byte: a 3-byte timestamp and three 2-byte channels */ + private static final int PACKET_SIZE = 9; + + /** Docked, sensing, RTC set and streaming; not SD logging */ + private static final byte STATUS_DOCKED_AND_STREAMING = 0x17; + + private static class QueueRadio implements ByteCommunication { + final Deque rx = new ArrayDeque(); + + void queue(byte... bytes) { + for(byte b:bytes){ + rx.add(b); + } + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() expected = new ArrayList(); + for(byte[] payload:expectedPayloads){ + expected.add(UtilShimmer.bytesToHexStringWithSpacesFormatted(payload)); + } + List parsed = new ArrayList(); + // Package-private, so ShimmerPC does not inherit it + ShimmerBluetooth device = mDevice; + for(RawBytePacketWithPCTimeStamp packet:device.mABQPacketByeArray){ + parsed.add(UtilShimmer.bytesToHexStringWithSpacesFormatted(packet.mDataArray)); + } + assertEquals("every data packet is parsed, once and in order", expected, parsed); + } + + private void assertCompleted() { + assertFalse("the ACK is taken", mDevice.mWaitForAck); + assertFalse("the next instruction can be sent", mDevice.isInstructionStackLock()); + assertNull("the ACK timer is cancelled", mDevice.mTimerCheckForAckOrResp); + } + + /** GET_STATUS_COMMAND sent in the pause: its reply must complete it, and nothing queued behind it may be lost */ + private void statusReplyInThePause(BT_CRC_MODE crcMode) { + streamingShimmer3r(crcMode); + mDevice.stopSDLogging(); + mDevice.readStatusLogAndStream(); + mDevice.readBattery(); + stopLoggingAndReceiveItsAck(crcMode); + + sendNextInstruction(); + assertEquals(ShimmerObject.GET_STATUS_COMMAND, mDevice.mCurrentCommand); + receive(statusReply(crcMode), dataPacket(2, crcMode), dataPacket(3, crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertCompleted(); + assertTrue("the status reply is decoded", mDevice.isDocked()); + assertEquals("GET_VBATT_COMMAND is still queued", 1, mDevice.getListofInstructions().size()); + assertEquals(ShimmerObject.GET_VBATT_COMMAND, mDevice.getListofInstructions().get(0)[0]); + assertParsed(payload(1), payload(2), payload(3)); + } + + @Test + public void statusReplyInThePauseWithOneByteCrc() { + statusReplyInThePause(BT_CRC_MODE.ONE_BYTE_CRC); + } + + @Test + public void statusReplyInThePauseWithTwoByteCrc() { + statusReplyInThePause(BT_CRC_MODE.TWO_BYTE_CRC); + } + + /** GET_VBATT_COMMAND sent in the pause */ + private void batteryReplyInThePause(BT_CRC_MODE crcMode) { + streamingShimmer3r(crcMode); + mDevice.stopSDLogging(); + mDevice.readBattery(); + stopLoggingAndReceiveItsAck(crcMode); + + sendNextInstruction(); + receive(vbattReply(crcMode), dataPacket(2, crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertCompleted(); + assertTrue(mDevice.getListofInstructions().isEmpty()); + assertEquals(0x0B24, mDevice.getBattStatusDetails().getBattAdcValue(), 0); + assertParsed(payload(1), payload(2)); + } + + @Test + public void batteryReplyInThePauseWithOneByteCrc() { + batteryReplyInThePause(BT_CRC_MODE.ONE_BYTE_CRC); + } + + @Test + public void batteryReplyInThePauseWithTwoByteCrc() { + batteryReplyInThePause(BT_CRC_MODE.TWO_BYTE_CRC); + } + + /** A SET command sent in the pause: its bare ACK must complete it */ + private void bareAckInThePause(BT_CRC_MODE crcMode) { + streamingShimmer3r(crcMode); + mDevice.stopSDLogging(); + mDevice.startSDLogging(); // SET_RWC_COMMAND, then START_LOGGING_ONLY_COMMAND + assertEquals(3, mDevice.getListofInstructions().size()); + stopLoggingAndReceiveItsAck(crcMode); + + sendNextInstruction(); + assertEquals(ShimmerObject.SET_RWC_COMMAND, mDevice.mCurrentCommand); + receive(bareAck(crcMode), dataPacket(2, crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertCompleted(); + assertEquals("START_LOGGING_ONLY_COMMAND is still queued", 1, mDevice.getListofInstructions().size()); + assertEquals(ShimmerObject.START_LOGGING_ONLY_COMMAND, mDevice.getListofInstructions().get(0)[0]); + assertParsed(payload(1), payload(2)); + } + + @Test + public void bareAckInThePauseWithOneByteCrc() { + bareAckInThePause(BT_CRC_MODE.ONE_BYTE_CRC); + } + + @Test + public void bareAckInThePauseWithTwoByteCrc() { + bareAckInThePause(BT_CRC_MODE.TWO_BYTE_CRC); + } + + /** + * An ACK at the start of the buffer is taken only for the reply the command in + * flight expects: a status push there does not complete GET_VBATT_COMMAND. + */ + private void anotherReplyAtTheStartIsNotTaken(BT_CRC_MODE crcMode) { + streamingShimmer3r(crcMode); + mDevice.readBattery(); + sendNextInstruction(); + + receive(statusReply(crcMode), dataPacket(1, crcMode), dataPacket(2, crcMode)); + assertEquals("GET_VBATT_COMMAND is still in flight", ShimmerObject.GET_VBATT_COMMAND, mDevice.mCurrentCommand); + assertTrue("it is still waiting for its ACK", mDevice.mWaitForAck); + assertTrue("the next instruction is not sent before it completes", mDevice.isInstructionStackLock()); + assertEquals(1, mDevice.getListofInstructions().size()); + } + + @Test + public void anotherReplyAtTheStartIsNotTakenWithOneByteCrc() { + anotherReplyAtTheStartIsNotTaken(BT_CRC_MODE.ONE_BYTE_CRC); + } + + @Test + public void anotherReplyAtTheStartIsNotTakenWithTwoByteCrc() { + anotherReplyAtTheStartIsNotTaken(BT_CRC_MODE.TWO_BYTE_CRC); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00033_InstructionListLockOrderTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00033_InstructionListLockOrderTest.java new file mode 100644 index 000000000..19a734f3c --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00033_InstructionListLockOrderTest.java @@ -0,0 +1,111 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.lang.management.ManagementFactory; +import java.lang.reflect.Method; +import java.util.concurrent.CountDownLatch; + +import org.junit.After; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunicationSimulatorS3; +import com.shimmerresearch.shimmer3.communication.ByteCommunicationTestUtils; + +/** + * DEV-1266: ShimmerBluetooth guards its instruction list with two locks, the + * device (its synchronized methods) and the list itself. Every accessor took + * them device first, list second, but getInstruction(), which the IO thread + * calls for the next instruction, took the list and then called the + * synchronized getListofInstructions(). So the IO thread could hold the list + * while waiting for the device, as a timer (the ACK/response timeout calling + * clearAllInstructions(), or the read-status timer) held the device while + * waiting for the list. Both then waited for good, and so did every later API + * call. The Android HIL caught it on a Shimmer3 (stopSDLogging() never + * returned), and it was the Linux CI hang in DEV-1198. + */ +public class API_00033_InstructionListLockOrderTest { + + private static final long TIMEOUT_MS = 5000; + + /** Only for the connect test: tearDown must not touch a device whose lock a deadlock may still hold */ + private ShimmerPC mDevice; + + @After + public void tearDown() { + if(mDevice!=null){ + mDevice.disconnectNoException(); + } + } + + /** + * The two locks taken the way they collided: a timer holds the device, as + * every synchronized accessor does, while the IO thread asks for the next + * instruction; the timer then queues an instruction, which needs the list. + * The IO thread's real getInstruction() is called, as it is private. + */ + @Test + public void theIoThreadAndATimerTakeTheTwoLocksInOneOrder() throws Exception { + ShimmerPC device = new ShimmerPC("COM99"); + device.readBattery(); // getInstruction() reads the head of a non-empty list + Method getInstruction = ShimmerBluetooth.class.getDeclaredMethod("getInstruction"); + getInstruction.setAccessible(true); + + CountDownLatch timerHoldsTheDevice = new CountDownLatch(1); + Thread ioThread = daemon("IO thread", () -> { + try { + timerHoldsTheDevice.await(); + getInstruction.invoke(device); + } catch (Exception e) { + throw new RuntimeException(e); + } + }); + Thread timer = daemon("timer", () -> { + synchronized(device){ + timerHoldsTheDevice.countDown(); + // Wait until the IO thread is either done or stuck waiting for the device + while(ioThread.getState()!=Thread.State.BLOCKED && ioThread.getState()!=Thread.State.TERMINATED){ + Thread.yield(); + } + device.readBattery(); // writeInstruction(): the device, then the list + } + }); + ioThread.start(); + timer.start(); + + ioThread.join(TIMEOUT_MS); + timer.join(TIMEOUT_MS); + long[] deadlocked = ManagementFactory.getThreadMXBean().findDeadlockedThreads(); + assertNull("the IO thread and the timer deadlocked on the device and the instruction list:\n" + + ByteCommunicationTestUtils.dumpAllThreads(), deadlocked); + assertFalse("the IO thread finished", ioThread.isAlive()); + assertFalse("the timer finished", timer.isAlive()); + assertEquals("both instructions are queued", 2, device.getListofInstructions().size()); + } + + /** + * The product as it runs: the read-status timer is left on, so it queues + * GET_STATUS_COMMAND from its own thread while the IO thread works through the + * connect sequence. The simulator tests otherwise build their device without it + * (ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer), since DEV-1198. + */ + @Test + public void connectsWithTheStatusTimerOn() { + for(int i=1;i<=5;i++){ + mDevice = new ShimmerPC("COM99"); + mDevice.setTestRadio(new ByteCommunicationSimulatorS3("COM99")); + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + assertEquals("connect " + i, BT_STATE.CONNECTED, mDevice.getBluetoothRadioState()); + mDevice.disconnectNoException(); + } + mDevice = null; + } + + private Thread daemon(String name, Runnable runnable) { + Thread thread = new Thread(runnable, name); + thread.setDaemon(true); // a deadlocked pair must not keep the test JVM alive + return thread; + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00034_DeepCloneWhileBusyTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00034_DeepCloneWhileBusyTest.java new file mode 100644 index 000000000..678bce6a1 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00034_DeepCloneWhileBusyTest.java @@ -0,0 +1,169 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicReference; + +import org.junit.After; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunicationSimulatorS3; +import com.shimmerresearch.shimmer3.communication.ByteCommunicationTestUtils; + +/** + * DEV-1310: ShimmerPC.deepClone() copies a device by serialising it, and Consensys's + * Bluetooth manager configures a connected device through such a copy. Serialisation + * takes no lock, so on a connected device the timers and the IO thread went on changing + * its instruction list while it was copied: the status timer queues GET_STATUS every + * 5 s, the battery timer queues a battery read, and the IO thread removes each + * instruction it sends. A change mid-copy threw ConcurrentModificationException out of + * deepClone(), and the configure failed. While streaming the same happened with the PC + * timestamp list, and a packet waiting for the processing thread made deepClone() return null. + *

+ * A clone is a copy of the configuration, not of the connection, so it now starts with + * none of the connection's queues. + */ +public class API_00034_DeepCloneWhileBusyTest { + + private static final int CLONES = 200; + + private ShimmerPC mDevice; + + @After + public void tearDown() { + if(mDevice!=null){ + mDevice.disconnectNoException(); + } + } + + /** + * Another thread queues an instruction the way a timer does (readBattery() takes the + * device, then the list) and retires one the way the IO thread does, while this one + * copies the device. A long queue keeps the copy of the list busy for long enough that + * nearly every clone overlaps a change. + */ + @Test + public void clonesWhileATimerQueuesInstructions() throws Exception { + ShimmerPC device = new ShimmerPC("COM99"); + for(int i=0;i<2000;i++){ + device.readBattery(); + } + AtomicBoolean stop = new AtomicBoolean(); + Thread timer = daemon("timer", () -> { + while(!stop.get()){ + device.readBattery(); + device.removeInstruction(0); + } + }); + timer.start(); + try { + for(int i=1;i<=CLONES;i++){ + ShimmerPC clone = device.deepClone(); + assertNotNull("clone " + i, clone); + assertTrue("clone " + i + " carries no instructions", clone.getListofInstructions().isEmpty()); + } + } finally { + stop.set(true); + timer.join(5000); + } + assertFalse("the queue was not copied away from the device", device.getListofInstructions().isEmpty()); + } + + /** + * While streaming, the IO thread notes the PC time as each packet starts and drops it once the + * packet is parsed. On a Shimmer3 streaming at 256 Hz that raced about one clone in a hundred. + */ + @Test + public void clonesWhileTheIoThreadTimestampsPackets() throws Exception { + ShimmerPC device = new ShimmerPC("COM99"); + for(int i=0;i<2000;i++){ + device.mListofPCTimeStamps.add(System.currentTimeMillis()); + } + AtomicBoolean stop = new AtomicBoolean(); + Thread ioThread = daemon("IO thread", () -> { + while(!stop.get()){ + device.mListofPCTimeStamps.add(System.currentTimeMillis()); + device.mListofPCTimeStamps.remove(0); + } + }); + ioThread.start(); + try { + for(int i=1;i<=CLONES;i++){ + ShimmerPC clone = device.deepClone(); + assertNotNull("clone " + i, clone); + assertTrue("clone " + i + " carries no PC timestamps", clone.mListofPCTimeStamps.isEmpty()); + } + } finally { + stop.set(true); + ioThread.join(5000); + } + } + + /** + * With the processing thread on, parsed packets wait in a queue for it. Its packets can't be + * serialised, so deepClone() returned null whenever one was waiting. + */ + @Test + public void clonesWithPacketsWaitingForTheProcessingThread() { + ShimmerPC device = new ShimmerPC("COM99"); + // The queue is package-private to ShimmerBluetooth, so reach it through that type + ShimmerBluetooth original = device; + original.mABQPacketByeArray.add(new RawBytePacketWithPCTimeStamp(new byte[] {ShimmerObject.DATA_PACKET, 0x01, 0x02}, System.currentTimeMillis())); + ShimmerBluetooth clone = device.deepClone(); + assertNotNull("a device with a packet waiting can be copied", clone); + assertTrue("the copy has no packets waiting", clone.mABQPacketByeArray.isEmpty()); + assertEquals("the device keeps its packet", 1, original.mABQPacketByeArray.size()); + } + + /** + * The product as it runs: a device connected to the simulator with its status timer on, + * an app thread reading the battery and status as Consensys does, and clones taken all + * the while. Each clone must be usable to configure from. + */ + @Test + public void clonesAConnectedDeviceWhileItWorksThroughItsQueue() throws Exception { + mDevice = new ShimmerPC("COM99"); + mDevice.setTestRadio(new ByteCommunicationSimulatorS3("COM99")); + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + assertEquals(BT_STATE.CONNECTED, mDevice.getBluetoothRadioState()); + + AtomicBoolean stop = new AtomicBoolean(); + AtomicReference appFailure = new AtomicReference<>(); + Thread app = daemon("app", () -> { + try { + while(!stop.get()){ + if(mDevice.getListofInstructions().size()<8){ + mDevice.readBattery(); + mDevice.readStatusLogAndStream(); + } + Thread.yield(); + } + } catch (Throwable t) { + appFailure.set(t); + } + }); + app.start(); + try { + for(int i=1;i<=CLONES;i++){ + ShimmerPC clone = mDevice.deepClone(); + assertNotNull("clone " + i, clone); + assertTrue("clone " + i + " carries no instructions", clone.getListofInstructions().isEmpty()); + assertEquals("clone " + i + " has the device's rate", mDevice.getSamplingRateShimmer(), clone.getSamplingRateShimmer(), 0); + } + } finally { + stop.set(true); + app.join(5000); + } + assertNull("the app thread failed", appFailure.get()); + } + + private Thread daemon(String name, Runnable runnable) { + Thread thread = new Thread(runnable, name); + thread.setDaemon(true); + return thread; + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/guiUtilities/plot/API_00029_LiveViewportFrameClockTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/guiUtilities/plot/API_00029_LiveViewportFrameClockTest.java new file mode 100644 index 000000000..00e9cc395 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/guiUtilities/plot/API_00029_LiveViewportFrameClockTest.java @@ -0,0 +1,202 @@ +package com.shimmerresearch.guiUtilities.plot; + +import static org.junit.Assert.*; + +import java.lang.reflect.Field; +import java.util.ArrayList; + +import org.junit.Before; +import org.junit.Test; + +import info.monitorenter.gui.chart.Chart2D; + +/** DEV-896: pins the live X viewport frame clock's core invariants without Swing: the tests drive + * updateFrameClockNewestX() (data thread side) and computeLiveViewportEnd() (EDT side) directly + * with a synthetic nanoTime, so they are deterministic and need no display. */ +public class API_00029_LiveViewportFrameClockTest { + + private static final double X0 = 1.78e12; //epoch ms, like System_Timestamp_Plot + private static final long T0_NS = 1_000_000_000L; + private static final double TICK_MS = 16; + + private BasicPlotManagerPC pm; + private Field fNewestX, fNewestXNanos; + + @Before + public void setUp() throws Exception { + pm = new BasicPlotManagerPC(new ArrayList(), 3000, new Chart2D()); + fNewestX = BasicPlotManagerPC.class.getDeclaredField("mFrameClockNewestX"); + fNewestXNanos = BasicPlotManagerPC.class.getDeclaredField("mFrameClockNewestXNanos"); + fNewestX.setAccessible(true); + fNewestXNanos.setAccessible(true); + } + + private static long ns(double ms){ return T0_NS + (long)(ms*1e6); } + + private double newestX() throws Exception { return fNewestX.getDouble(pm); } + + private double tick(double tMs) throws Exception { + return pm.computeLiveViewportEnd(ns(tMs), fNewestX.getDouble(pm), fNewestXNanos.getLong(pm)); + } + + /** 256 Hz, delivered in bursts every burstMs, X = arrival time - 20 ms; deliveries in + * [stallFrom, stallTo) are held back and arrive together at stallTo. */ + private void deliver(double fromMs, double toMs, double burstMs, double stallFrom, double stallTo){ + for(double bt=Math.floor(fromMs/burstMs)*burstMs+burstMs; bt<=toMs; bt+=burstMs){ + if(bt>=stallFrom && bt=stallTo && bt-burstMs2000){ + double step = end-prevEnd; + assertTrue("never backwards", step >= 0); + assertEquals("one tick = one tick of X, within the 10% slew", TICK_MS, step, TICK_MS*0.11); + double hidden = newestX()-end; + assertTrue("never ahead of the newest sample", hidden >= 0); + assertTrue("trails by about VIEWPORT_LATENCY_MS: "+hidden, + hidden <= BasicPlotManagerPC.VIEWPORT_LATENCY_MS + 60); + assertTrue("lag stays inside the trace margin", + hidden <= BasicPlotManagerPC.LIVE_VIEWPORT_TRACE_MARGIN_MS); + } + prevEnd = end; + } + } + + @Test + public void dataStall_freezesWithoutBackwardSteps_thenCatchesUpWithinASecond() throws Exception { + double prevEnd = Double.NaN, recoveredAt = -1; + double stallFrom = 10000, stallTo = 10600; + for(double t=TICK_MS; t<16000; t+=TICK_MS){ + deliver(t-TICK_MS, t, 60, stallFrom, stallTo); + double end = tick(t); + if(!Double.isNaN(prevEnd)){ + assertTrue("never backwards", end >= prevEnd); + assertTrue("at most 2x real time while catching up (no snap below 1 s)", + t < 2000 || end-prevEnd <= 2*TICK_MS + 1e-6); + } + assertTrue("never ahead of the newest sample", end <= newestX()); + if(t>stallTo && recoveredAt<0 && newestX()-end < BasicPlotManagerPC.VIEWPORT_LATENCY_MS+60){ + recoveredAt = t; + } + prevEnd = end; + } + assertTrue("caught up within 1 s of the stall ending: "+recoveredAt, recoveredAt>0 && recoveredAt-stallTo <= 1000); + } + + /** While catching up after a stall the window trails the newest sample by more than in steady + * running; the trace margin must cover that lag at every stall length up to the resync + * threshold, or a blank strip shows at the window's left edge until it has caught up. */ + @Test + public void dataStall_lagStaysWithinTraceMargin_forStallsUpToResync() throws Exception { + for(double stallMs : new double[]{300, 600, 900, 980}){ + setUp(); + double stallFrom = 10000, stallTo = stallFrom+stallMs, worstLag = 0; + for(double t=TICK_MS; t<14000; t+=TICK_MS){ + deliver(t-TICK_MS, t, 60, stallFrom, stallTo); + double end = tick(t); + if(t>2000){ + worstLag = Math.max(worstLag, newestX()-end); + } + } + assertTrue("stall "+stallMs+" ms: lag "+worstLag+" within the trace margin", + worstLag <= BasicPlotManagerPC.LIVE_VIEWPORT_TRACE_MARGIN_MS); + } + } + + @Test + public void longEdtStall_stepIsElapsedTimeNotDoubled() throws Exception { + double t = 0, prevT = 0, prevEnd = Double.NaN; + while(t < 12000){ + double next = t + ((t>=10000 && t<10000+TICK_MS) ? 300 : TICK_MS); //one 300 ms EDT hiccup + deliver(t, next, 60, -1, -1); + t = next; + double end = tick(t); + if(t>2000){ + //slew branch: step <= elapsed + min(elapsed, 0.15 * error), error <= FRAME_CLOCK_RESYNC_MS + assertTrue("step "+(end-prevEnd)+" after "+(t-prevT)+" ms", end-prevEnd <= (t-prevT) + 150); + } + prevEnd = end; prevT = t; + } + } + + @Test + public void secondDeviceFarBehind_doesNotPullNewestBack() throws Exception { + for(double t=0; t<5000; t+=10){ + pm.updateFrameClockNewestX(X0+t, ns(t)); + pm.updateFrameClockNewestX(X0+t-1500, ns(t+1)); //device B, 1.5 s behind + assertEquals(X0+t, newestX(), 0); + } + } + + @Test + public void genuineBackwardJump_resetsAfterConfirmation_singleSnap() throws Exception { + double prevEnd = Double.NaN; int backwardSteps = 0; + for(double t=TICK_MS; t<20000; t+=TICK_MS){ + double x = X0 + t - 30 + (t>=10000 ? -60_000 : 0); //device clock reset by a minute + pm.updateFrameClockNewestX(x, ns(t-2)); + double end = tick(t); + if(!Double.isNaN(prevEnd) && end3000){ + double step = end-prevEnd; + assertTrue("never backwards", step >= 0); + assertTrue("no single-tick step > 100 ms: "+step+" at "+t, step <= 100); + double lag = newestX()-end; + assertTrue("lag "+lag+" within the trace margin", lag <= BasicPlotManagerPC.LIVE_VIEWPORT_TRACE_MARGIN_MS); + } + prevEnd = end; + } + } + + /** A 2 Hz series (e.g. the fusion-response plot) must not rubber-band: the window may wait for + * the next sample, but never stays frozen for longer than one sample interval. */ + @Test + public void twoHzData_noFrozenRunLongerThanOneSampleInterval() throws Exception { + double intervalMs = 500, nextSample = 0, prevEnd = Double.NaN, frozenSince = -1, longestFrozen = 0; + for(double t=TICK_MS; t<30000; t+=TICK_MS){ + while(nextSample<=t){ + pm.updateFrameClockNewestX(X0+nextSample-20, ns(nextSample)); + nextSample += intervalMs; + } + double end = tick(t); + if(t>5000){ + assertTrue("never backwards", end >= prevEnd); + if(end==prevEnd){ + if(frozenSince<0) frozenSince = t-TICK_MS; + longestFrozen = Math.max(longestFrozen, t-frozenSince); + } + else{ + frozenSince = -1; + } + } + prevEnd = end; + } + assertTrue("longest frozen run "+longestFrozen+" ms", longestFrozen <= intervalMs); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilReport.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilReport.java new file mode 100644 index 000000000..683586284 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilReport.java @@ -0,0 +1,161 @@ +package com.shimmerresearch.hil; + +import java.io.File; +import java.io.IOException; +import java.io.Writer; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.text.SimpleDateFormat; +import java.util.ArrayList; +import java.util.Date; +import java.util.List; +import java.util.Locale; +import java.util.Map; + +import com.google.gson.GsonBuilder; +import com.google.gson.JsonArray; +import com.google.gson.JsonElement; +import com.google.gson.JsonNull; +import com.google.gson.JsonObject; +import com.google.gson.JsonPrimitive; + +/** + * Everything one scenario run found: a JSON report, a CSV of the samples it judged and the + * driver's own log, written to the folder the runner passes (hil.outDir). + */ +final class HilReport { + + private final String scenario; + private final String unit; + private final JsonObject json = new JsonObject(); + private final List failures = new ArrayList<>(); + private List samples; + + HilReport(String scenario, String unit, String port, String mac, String type, Map args) { + this.scenario = scenario; + this.unit = unit; + json.addProperty("scenario", scenario); + json.addProperty("unit", unit); + json.addProperty("port", port); + json.addProperty("mac", mac); + json.addProperty("type", type); + json.addProperty("started", new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ", Locale.ROOT).format(new Date())); + JsonObject a = new JsonObject(); + args.forEach(a::addProperty); + json.add("args", a); + } + + /** JSON has no NaN or infinity, and a failing run is the likeliest to produce one: store null. */ + static JsonElement num(double v) { + return Double.isNaN(v) || Double.isInfinite(v) ? JsonNull.INSTANCE : new JsonPrimitive(v); + } + + void put(String key, Object value) { + if (value == null) { + json.add(key, JsonNull.INSTANCE); + } else if (value instanceof Double || value instanceof Float) { + json.add(key, num(((Number) value).doubleValue())); + } else if (value instanceof Number) { + json.addProperty(key, (Number) value); + } else if (value instanceof Boolean) { + json.addProperty(key, (Boolean) value); + } else if (value instanceof Map) { + JsonObject o = new JsonObject(); + ((Map) value).forEach((k, v) -> o.addProperty(String.valueOf(k), v instanceof Number ? (Number) v : null)); + json.add(key, o); + } else if (value instanceof List) { + JsonArray arr = new JsonArray(); + for (Object o : (List) value) { + arr.add(o instanceof Number ? new JsonPrimitive((Number) o) : new JsonPrimitive(String.valueOf(o))); + } + json.add(key, arr); + } else { + json.addProperty(key, String.valueOf(value)); + } + } + + void putStream(String key, StreamAnalysis a) { + JsonObject o = new JsonObject(); + o.addProperty("received", a.received); + o.addProperty("missing", a.missing); + o.add("lossPercent", num(a.lossPercent())); + o.addProperty("nonIncreasing", a.nonIncreasing); + o.addProperty("timestampJumps", a.timestampJumps.size()); + o.add("effectiveRateHz", num(a.effectiveRateHz)); + o.add("accelMagnitudeMean", num(a.accelMagnitudeMean)); + o.add("accelMagnitudeStd", num(a.accelMagnitudeStd)); + o.addProperty("gaps", a.gaps.size()); + json.add(key, o); + } + + /** Every gap and timestamp jump, with when it arrived, to match against what the test was doing. */ + void putGaps(StreamAnalysis a) { + JsonArray gaps = new JsonArray(); + for (StreamAnalysis.Gap g : a.gaps) { + JsonObject o = new JsonObject(); + o.addProperty("afterReceivedMs", Math.round(g.afterReceivedMs)); + o.add("afterTimestampMs", num(g.afterTimestampMs)); + o.addProperty("missing", g.missing); + gaps.add(o); + } + json.add("gapList", gaps); + JsonArray jumps = new JsonArray(); + for (StreamAnalysis.Gap g : a.timestampJumps) { + JsonObject o = new JsonObject(); + o.addProperty("afterReceivedMs", Math.round(g.afterReceivedMs)); + o.add("afterTimestampMs", num(g.afterTimestampMs)); + o.addProperty("periodsAhead", g.missing + 1); + jumps.add(o); + } + json.add("timestampJumpList", jumps); + } + + void samples(List samples) { + this.samples = samples; + } + + /** Records a failed check; the test fails at the end with every one of them. */ + void check(boolean ok, String failure) { + if (!ok) { + failures.add(failure); + System.out.println(scenario + " " + unit + " FAIL: " + failure); + } + } + + List failures() { + return failures; + } + + /** Writes _.json, .csv (samples, if any) and .driver.log into outDir. */ + void write(File outDir, List events, List driverLog) { + try { + json.addProperty("passed", failures.isEmpty()); + JsonArray f = new JsonArray(); + failures.forEach(f::add); + json.add("failures", f); + JsonArray e = new JsonArray(); + events.forEach(e::add); + json.add("events", e); + if (!outDir.exists() && !outDir.mkdirs()) { + throw new IOException("cannot create " + outDir); + } + String base = scenario + "_" + unit.replaceAll("[^\\w.-]", "_"); + try (Writer w = Files.newBufferedWriter(new File(outDir, base + ".json").toPath(), StandardCharsets.UTF_8)) { + new GsonBuilder().setPrettyPrinting().create().toJson(json, w); + } + if (samples != null) { + try (Writer w = Files.newBufferedWriter(new File(outDir, base + ".csv").toPath(), StandardCharsets.UTF_8)) { + w.write("received_ms,timestamp_ms,accel_x,accel_y,accel_z\n"); + for (StreamAnalysis.Sample s : samples) { + w.write(String.format(Locale.ROOT, "%.0f,%.3f,%.4f,%.4f,%.4f\n", + s.receivedMs, s.timestampMs, s.accelX, s.accelY, s.accelZ)); + } + } + } + Files.write(new File(outDir, base + ".driver.log").toPath(), driverLog, StandardCharsets.UTF_8); + System.out.println("report written: " + new File(outDir, base + ".json")); + } catch (IOException ex) { + System.out.println("could not write report: " + ex); + } + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilSession.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilSession.java new file mode 100644 index 000000000..440d4d8e4 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilSession.java @@ -0,0 +1,384 @@ +package com.shimmerresearch.hil; + +import java.util.ArrayList; +import java.util.Collection; +import java.util.HashSet; +import java.util.List; +import java.util.Locale; +import java.util.Set; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.TimeoutException; +import java.util.regex.Pattern; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.driver.BasicProcessWithCallBack; +import com.shimmerresearch.driver.CallbackObject; +import com.shimmerresearch.driver.Configuration; +import com.shimmerresearch.driver.FormatCluster; +import com.shimmerresearch.driver.ObjectCluster; +import com.shimmerresearch.driver.ShimmerDevice; +import com.shimmerresearch.driver.ShimmerMsg; +import com.shimmerresearch.driverUtilities.AssembleShimmerConfig; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails; +import com.shimmerresearch.shimmer3.communication.ByteCommunicationTestUtils; + +/** + * One unit on one serial port, driven through ShimmerPC as an app drives it. Every API call runs + * under a watchdog: if one does not return, the session records which, dumps every thread (with + * the locks each holds and waits on) and refuses further calls, so a deadlock ends the scenario + * with evidence instead of hanging the run. + */ +class HilSession extends BasicProcessWithCallBack implements AutoCloseable { + + interface Call { + void run() throws Exception; + } + + interface Condition { + boolean holds(); + } + + final String port; + final String mac; + final String type; + final HilShimmerPC device; + private final long t0 = System.nanoTime(); + private final List events = new ArrayList<>(); + private final List samples = new ArrayList<>(); + /** Each recorded packet's raw device ticks (TIMESTAMP, UNCAL), since startRecording, across stretches. */ + private final List rawTicks = new ArrayList<>(); + private final Set otherMessagesSeen = new HashSet<>(); + private final ExecutorService calls = Executors.newSingleThreadExecutor(r -> { + Thread t = new Thread(r, "HilCall"); + t.setDaemon(true); + return t; + }); + private volatile boolean recording; + private volatile BT_STATE lastState; + /** State changes reported so far, so a connect can tell its own CONNECTION_FAILED from the last one's. */ + private volatile int stateChanges; + /** The call that never returned, if one did not. */ + volatile String hung; + /** Connects made in this session, for the report: each is a chance for the connect-time race. */ + int connects; + /** Why the last connect failed, as a sentence for the report; null after one that succeeded. */ + volatile String connectFailure; + /** jssc's message when Windows refuses to open a COM port that another program already has open. */ + private static final Pattern PORT_BUSY = Pattern.compile("Port busy"); + /** + * Per connect: whether the driver has sent NOTIFICATION_SHIMMER_FULLY_INITIALIZED (the end of + * its connect sequence), and whether the first CONNECTED state is still to come. + */ + private volatile boolean fullyInitialisedSinceConnect; + private volatile boolean awaitingFirstConnected; + /** + * Connects whose first CONNECTED came before the end of the connect sequence: the app was told + * the unit was ready while the sequence was still queued (DEV-1275). + */ + volatile int connectedBeforeReady; + + HilSession(String port, String mac, String type) { + this.port = port; + this.mac = mac; + this.type = type; + this.device = new HilShimmerPC(port, t0); + setWaitForData(device); + } + + double nowMs() { + return (System.nanoTime() - t0) / 1e6; + } + + void event(String text) { + String line = String.format(Locale.ROOT, "%9.0f %s", nowMs(), text); + synchronized (events) { + events.add(line); + } + System.out.println(port + " " + line); + } + + List events() { + synchronized (events) { + return new ArrayList<>(events); + } + } + + @Override + protected void processMsgFromCallback(ShimmerMsg msg) { + if (msg.mIdentifier == HilShimmerPC.MSG_IDENTIFIER_STATE_CHANGE && msg.mB instanceof CallbackObject) { + BT_STATE state = ((CallbackObject) msg.mB).mState; + if (state != null) { + lastState = state; + stateChanges++; + event("state " + state); + if (state == BT_STATE.CONNECTED && awaitingFirstConnected) { + awaitingFirstConnected = false; + if (!fullyInitialisedSinceConnect) { + connectedBeforeReady++; + event("CONNECTED reported before the connect sequence ended (no FULLY_INITIALIZED yet; DEV-1275)"); + } + } + } + } else if (msg.mIdentifier == HilShimmerPC.MSG_IDENTIFIER_NOTIFICATION_MESSAGE && msg.mB instanceof CallbackObject + && ((CallbackObject) msg.mB).mIndicator == HilShimmerPC.NOTIFICATION_SHIMMER_FULLY_INITIALIZED) { + fullyInitialisedSinceConnect = true; + event("fully initialised"); + } else if (msg.mIdentifier == HilShimmerPC.MSG_IDENTIFIER_DATA_PACKET && msg.mB instanceof ObjectCluster) { + if (recording) { + recordPacket((ObjectCluster) msg.mB); + } + } else if (otherMessagesSeen.add(msg.mIdentifier)) { + event("message " + msg.mIdentifier + (msg.mB == null ? "" : " " + msg.mB.getClass().getSimpleName())); + } + } + + private void recordPacket(ObjectCluster oc) { + StreamAnalysis.Sample s = new StreamAnalysis.Sample(nowMs(), + cal(oc, Configuration.Shimmer3.ObjectClusterSensorName.TIMESTAMP), + cal(oc, Configuration.Shimmer3.ObjectClusterSensorName.ACCEL_LN_X), + cal(oc, Configuration.Shimmer3.ObjectClusterSensorName.ACCEL_LN_Y), + cal(oc, Configuration.Shimmer3.ObjectClusterSensorName.ACCEL_LN_Z)); + double ticks = value(oc, Configuration.Shimmer3.ObjectClusterSensorName.TIMESTAMP, "UNCAL"); + synchronized (samples) { + samples.add(s); + rawTicks.add(ticks); + } + } + + private static double cal(ObjectCluster oc, String channel) { + return value(oc, channel, "CAL"); + } + + private static double value(ObjectCluster oc, String channel, String format) { + Collection formats = oc.getCollectionOfFormatClusters(channel); + FormatCluster c = (FormatCluster) ObjectCluster.returnFormatCluster(formats, format); + return c == null ? Double.NaN : c.mData; + } + + BT_STATE state() { + BT_STATE s = device.getBluetoothRadioState(); + return s != null ? s : lastState; + } + + boolean waitFor(Condition condition, long timeoutMs) throws InterruptedException { + long deadline = System.nanoTime() + timeoutMs * 1_000_000L; + while (System.nanoTime() < deadline) { + if (condition.holds()) { + return true; + } + Thread.sleep(20); + } + return condition.holds(); + } + + /** + * Runs an API call under the watchdog. After a hung call nothing more is run: the driver is in + * an unknown state, and queuing calls behind the stuck one only adds stuck threads. + */ + boolean call(String what, long timeoutMs, Call call) { + if (hung != null) { + event("skipped " + what + ": " + hung + " never returned"); + return false; + } + event(what); + Future f = calls.submit(() -> { + call.run(); + return null; + }); + try { + f.get(timeoutMs, TimeUnit.MILLISECONDS); + return true; + } catch (TimeoutException e) { + hung = what; + event(what + " did not return within " + timeoutMs + " ms; every thread:\n" + + ByteCommunicationTestUtils.dumpAllThreads()); + return false; + } catch (java.util.concurrent.ExecutionException e) { + event(what + " threw " + e.getCause()); + return false; + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + return false; + } + } + + /** + * Connects and waits until the driver has read the unit's configuration. A connect is never + * retried. When the port can't be opened, connectFailure says why. jssc's "Port busy" means + * another program on this PC has the port open (another HIL, Consensys, a serial terminal), so + * the unit is in use. Results taken while another host shares the unit mean nothing, and that is + * how DEV-1276 was misread. + */ + boolean connect(long timeoutMs) throws InterruptedException { + connects++; + connectFailure = null; + fullyInitialisedSinceConnect = false; + awaitingFirstConnected = true; + int mark = stateChanges; + int logMark = device.logSize(); + Condition failed = () -> stateChanges > mark && device.getBluetoothRadioState() == BT_STATE.CONNECTION_FAILED; + if (!call("connect on " + port, 10000, () -> device.connect(port, ""))) { + connectFailure = "connect on " + port + " did not return (see the events)"; + return false; + } + boolean ready = waitFor(() -> (device.isInitialised() && device.getBluetoothRadioState() == BT_STATE.CONNECTED) + || failed.holds(), timeoutMs) && !failed.holds(); + if (ready) { + event("connected: timers " + device.timers()); + } else { + if (device.countSince(logMark, PORT_BUSY) > 0) { + connectFailure = port + " is open in another program (another HIL, Consensys, a serial terminal?): " + + "jssc reports \"Port busy\". Nothing else may use the unit during a run."; + } else if (failed.holds()) { + connectFailure = "the Bluetooth link on " + port + " could not be opened (CONNECTION_FAILED): " + + "is the unit on, in range, and not connected to another host?"; + } else { + connectFailure = "did not connect and initialise within " + timeoutMs / 1000 + " s (state " + state() + ")"; + } + event(connectFailure); + } + return ready; + } + + /** + * Accel only (the low-noise accel on Shimmer3, the LSM6DSV's on Shimmer3R) at rateHz, written the + * way Consensys's Bluetooth manager does it: a clone, AssembleShimmerConfig, then + * operationPrepare, configureFromClone and operationStart(CONFIGURING) on the connected device, + * except that the calibration is not written back. + */ + boolean configureAccelOnly(double rateHz, long timeoutMs) throws InterruptedException { + ShimmerDevice clone = device.deepClone(); + clone.disableAllSensors(); + if (clone.getHardwareVersion() == ShimmerVerDetails.HW_ID.SHIMMER_3) { + clone.setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_ANALOG_ACCEL, true); + } else { + clone.setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_LSM6DSV_ACCEL_LN, true); + } + clone.setShimmerAndSensorsSamplingRate(rateHz); + AssembleShimmerConfig.generateSingleShimmerConfig(clone, Configuration.COMMUNICATION_TYPE.BLUETOOTH); + // Leave the unit's stored calibration alone. configureFromClone otherwise writes the clone's + // calibration dump back (AA-246), which would rewrite the bench units' calibration on every run. + ((ShimmerBluetooth) clone).setWriteCalibrationDumpWhenConfiguringForClone(false); + int logMark = device.logSize(); + boolean sent = call(String.format(Locale.ROOT, "configure accel only at %.1f Hz", rateHz), 10000, () -> { + device.operationPrepare(); + device.configureFromClone(clone); + device.operationStart(BT_STATE.CONFIGURING); + }); + if (!sent) { + return false; + } + // The operation ends by reading the configuration back, finishing with an INQUIRY. Wait for that + // reply (logged after this configure began), an empty queue and the requested rate read back: + // state and rate alone can already hold before the write starts, if the unit kept them. + boolean done = waitFor(() -> device.countSince(logMark, "Inquiry Response Received") > 0 + && device.queuedInstructions() == 0 && state() == BT_STATE.CONNECTED + && Math.abs(device.getSamplingRateShimmer() - rateHz) < 0.5, timeoutMs); + event(String.format(Locale.ROOT, "configure %s: rate on device %.2f Hz, timers %s", done ? "finished" : "timed out", + device.getSamplingRateShimmer(), device.timers())); + return done; + } + + void startRecording() { + synchronized (samples) { + samples.clear(); + rawTicks.clear(); + } + recording = true; + } + + /** + * The raw device ticks of every packet recorded since startRecording, in arrival order: the + * unit's own 3-byte counter, before the driver unwraps it (TimestampWraps counts its wraps). + */ + List rawTicksRecorded() { + synchronized (samples) { + return new ArrayList<>(rawTicks); + } + } + + List stopRecording() { + recording = false; + synchronized (samples) { + return new ArrayList<>(samples); + } + } + + /** + * Ends one stretch of the recording and starts the next, for when the test stops and restarts + * streaming on purpose: each stretch is judged on its own, so the pause is not taken for loss. + */ + List nextSegment() { + synchronized (samples) { + List done = new ArrayList<>(samples); + samples.clear(); + return done; + } + } + + /** + * Starts SD logging on a streaming unit the way Consensys does (PanelLiveData, DEV-436): stop + * streaming, start logging on the quiet link (SET_RWC, then START_LOGGING_ONLY), then stream + * again. The RTC is therefore never written mid-stream. The stretch recorded before the stop is + * returned, and recording carries on into a new one. + */ + List startSdLoggingLikeConsensys(String what, HilReport report) throws InterruptedException { + report.check(stopStreaming(10000), what + ": streaming did not stop before starting SD logging"); + List before = nextSegment(); + boolean started = call("startSDLogging", 10000, device::startSDLogging); + report.check(started, what + ": startSDLogging did not complete: it threw, hung or was skipped (see the events)"); + if (started) { + report.check(waitFor(device::isSDLogging, 5000), what + ": SD logging did not start (state " + state() + "; is there an SD card?)"); + } + report.check(startStreaming(10000), what + ": streaming did not restart after starting SD logging"); + report.check(waitFor(() -> state() == BT_STATE.STREAMING_AND_SDLOGGING, 5000), + what + ": not streaming and logging after the restart (state " + state() + ")"); + return before; + } + + boolean startStreaming(long timeoutMs) throws InterruptedException { + return call("startStreaming", 10000, device::startStreaming) && waitFor(device::isStreaming, timeoutMs); + } + + boolean stopStreaming(long timeoutMs) throws InterruptedException { + event("while streaming: timers " + device.timers()); + return call("stopStreaming", 10000, device::stopStreaming) && waitFor(() -> !device.isStreaming(), timeoutMs); + } + + boolean disconnect(long timeoutMs) throws InterruptedException { + return call("disconnect", 10000, device::disconnect) && waitFor(() -> { + BT_STATE s = state(); + return s == BT_STATE.DISCONNECTED || s == BT_STATE.CONNECTION_LOST; + }, timeoutMs); + } + + /** Instructions waiting to be sent, read as the driver's own accessors read them. */ + int queuedInstructions() { + return device.queuedInstructions(); + } + + @Override + public void close() { + try { + // After a hung call leave the unit alone; the runner's timeout ends the JVM. + if (hung == null) { + BT_STATE s = state(); + if (s != null && s != BT_STATE.DISCONNECTED && s != BT_STATE.CONNECTION_LOST) { + if (device.isStreaming()) { + stopStreaming(5000); + } + disconnect(10000); + } + } + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } finally { + removeSetWaitForData(device); + calls.shutdownNow(); + } + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilShimmerPC.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilShimmerPC.java new file mode 100644 index 000000000..8dfa48413 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilShimmerPC.java @@ -0,0 +1,201 @@ +package com.shimmerresearch.hil; + +import java.io.IOException; +import java.io.ObjectInputStream; +import java.util.ArrayList; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.TreeMap; + +import com.shimmerresearch.driverUtilities.ShimmerBattStatusDetails; +import com.shimmerresearch.pcDriver.ShimmerPC; + +/** + * A ShimmerPC that behaves exactly as an app's does (timers on, the real serial port) but counts + * what the tests need to see: each in-stream reply by type, each status the driver decoded, each + * battery reading, and every line the driver logs, whether or not verbose mode is on. Nothing here + * changes what the driver does. + */ +class HilShimmerPC extends ShimmerPC { + + private static final long serialVersionUID = 1L; + + /** Lines kept per session; enough for minutes of commands, bounded if something loops. */ + private static final int MAX_LOG_LINES = 50000; + + private final long t0; + // What the session counted is transient: the driver's threads add to it all the time, and + // configureAccelOnly copies this device by serialising it (deepClone()), which threw + // ConcurrentModificationException when a line was logged mid-copy (DEV-1310). + private transient Map inStreamReplies = new TreeMap<>(); + private transient List log = new ArrayList<>(); + private volatile int statusesDecoded; + private volatile int batteryReadings; + /** When each battery reply was decoded, in ms on the session's clock (HilSession.nowMs()). */ + private transient List batteryReplyTimesMs = new ArrayList<>(); + + HilShimmerPC(String comPort, long t0Nanos) { + super(comPort); + this.t0 = t0Nanos; + } + + /** A copy starts counting from nothing; a deserialised object runs no field initialisers. */ + private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException { + in.defaultReadObject(); + inStreamReplies = new TreeMap<>(); + log = new ArrayList<>(); + batteryReplyTimesMs = new ArrayList<>(); + } + + @Override + protected void processInstreamResponse(byte inStreamResponseCommand, boolean shouldClearCrcFromBuffer) { + synchronized (inStreamReplies) { + inStreamReplies.merge(replyName(inStreamResponseCommand), 1, Integer::sum); + } + super.processInstreamResponse(inStreamResponseCommand, shouldClearCrcFromBuffer); + } + + @Override + protected void eventLogAndStreamStatusChanged(byte currentCommand) { + statusesDecoded++; + super.eventLogAndStreamStatusChanged(currentCommand); + } + + @Override + public void setBattStatusDetails(ShimmerBattStatusDetails s) { + batteryReadings++; + synchronized (batteryReplyTimesMs) { + batteryReplyTimesMs.add((System.nanoTime() - t0) / 1e6); + } + super.setBattStatusDetails(s); + } + + List batteryReplyTimesMs() { + synchronized (batteryReplyTimesMs) { + return new ArrayList<>(batteryReplyTimesMs); + } + } + + @Override + public void consolePrintLn(String message) { + record(message); + super.consolePrintLn(message); + } + + @Override + public void consolePrintErrLn(String message) { + record("ERR " + message); + super.consolePrintErrLn(message); + } + + /** The driver prints an exception's message to System.out, past consolePrintLn; keep it in the log too. */ + @Override + protected void consolePrintException(String message, StackTraceElement[] stackTrace) { + record("EXCEPTION " + message); + super.consolePrintException(message, stackTrace); + } + + private void record(String message) { + String line = String.format(Locale.ROOT, "%9.0f %s", (System.nanoTime() - t0) / 1e6, message); + synchronized (log) { + if (log.size() < MAX_LOG_LINES) { + log.add(line); + } + } + } + + static String replyName(byte b) { + switch (b) { + case STATUS_RESPONSE: + return "STATUS"; + case DIR_RESPONSE: + return "DIR"; + case VBATT_RESPONSE: + return "VBATT"; + default: + return String.format(Locale.ROOT, "0x%02X", b & 0xFF); + } + } + + int inStreamReplies(String type) { + synchronized (inStreamReplies) { + return inStreamReplies.getOrDefault(type, 0); + } + } + + Map inStreamReplies() { + synchronized (inStreamReplies) { + return new TreeMap<>(inStreamReplies); + } + } + + /** Which of the driver's periodic timers exist right now: an app runs with all three. */ + String timers() { + List t = new ArrayList<>(); + if (mTimerReadStatus != null) { + t.add("status"); + } + if (mTimerCheckAlive != null) { + t.add("alive"); + } + if (mTimerReadBattStatus != null) { + t.add("battery"); + } + return t.isEmpty() ? "none" : String.join("+", t); + } + + /** Instructions waiting to be sent, read through the driver's own (synchronized) accessor. */ + int queuedInstructions() { + return getListofInstructions().size(); + } + + int statusesDecoded() { + return statusesDecoded; + } + + int batteryReadings() { + return batteryReadings; + } + + int logSize() { + synchronized (log) { + return log.size(); + } + } + + List log() { + synchronized (log) { + return new ArrayList<>(log); + } + } + + /** Lines logged since index from that match the pattern anywhere. */ + int countSince(int from, java.util.regex.Pattern pattern) { + int n = 0; + synchronized (log) { + for (int i = Math.max(0, from); i < log.size(); i++) { + if (pattern.matcher(log.get(i)).find()) { + n++; + } + } + } + return n; + } + + /** Lines logged since index from that contain any of the given texts. */ + int countSince(int from, String... texts) { + int n = 0; + synchronized (log) { + for (int i = Math.max(0, from); i < log.size(); i++) { + for (String t : texts) { + if (log.get(i).contains(t)) { + n++; + break; + } + } + } + } + return n; + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilShimmerPCTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilShimmerPCTest.java new file mode 100644 index 000000000..171946892 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilShimmerPCTest.java @@ -0,0 +1,50 @@ +package com.shimmerresearch.hil; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertNotNull; + +import java.util.concurrent.atomic.AtomicBoolean; + +import org.junit.Test; + +import com.shimmerresearch.pcDriver.ShimmerPC; + +/** + * configureAccelOnly copies the device the way Consensys does (deepClone()) while the driver's + * threads keep logging into it. The copy must not trip over the log (DEV-1310). + */ +public class HilShimmerPCTest { + + @Test + public void clonesWhileTheDriverLogs() throws Exception { + HilShimmerPC device = new HilShimmerPC("COM99", System.nanoTime()); + for (int i = 0; i < 5000; i++) { + device.consolePrintLn("line " + i); + } + AtomicBoolean stop = new AtomicBoolean(); + // A line a millisecond or so: often enough to land in most copies, slowly enough to stay + // under the log's cap (MAX_LOG_LINES), past which it no longer changes + Thread driver = new Thread(() -> { + while (!stop.get()) { + device.consolePrintLn("GET_STATUS_COMMAND Instruction added"); + try { + Thread.sleep(1); + } catch (InterruptedException e) { + return; + } + } + }, "driver"); + driver.setDaemon(true); + driver.start(); + try { + for (int i = 1; i <= 100; i++) { + ShimmerPC clone = device.deepClone(); + assertNotNull("clone " + i, clone); + assertEquals("clone " + i + " starts its own log", 0, ((HilShimmerPC) clone).logSize()); + } + } finally { + stop.set(true); + driver.join(5000); + } + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/JavaHilScenariosTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/JavaHilScenariosTest.java new file mode 100644 index 000000000..453c92756 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/JavaHilScenariosTest.java @@ -0,0 +1,800 @@ +package com.shimmerresearch.hil; + +import static org.junit.Assume.assumeTrue; + +import java.io.File; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Locale; +import java.util.Map; + +import org.junit.After; +import org.junit.Assert; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_CRC_MODE; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; + +/** + * Hardware-in-the-loop scenarios for the Java driver: a real Shimmer3 or Shimmer3R on a paired + * Bluetooth serial port, driven through ShimmerPC with its timers on, as Consensys and MATLAB run + * it. Run by tools/hil/run-java-hil.ps1 through the hilTest task, one scenario per JVM. Without + * hil.port every test is skipped, so the class never runs (or fails) without hardware. + * + *

+ *   hil.port            COM port of the unit (required)
+ *   hil.mac, hil.unit   for the report
+ *   hil.type            Shimmer3 (default) or Shimmer3R
+ *   hil.rate            sampling rate in Hz, default 256
+ *   hil.seconds         streamRest duration, default 30
+ *   hil.cycles          midStreamSet / reconnectLoop / inStream repetitions, default 3 / 5 / 3
+ *   hil.overlaps        inStream overlap rounds, default 5
+ *   hil.threads         queueStress app threads, default 4
+ *   hil.stressSeconds   queueStress duration, default 60
+ *   hil.maxQueued       queueStress queue length the threads keep below, default 8
+ *   hil.stallSeconds    queueStress: no progress for this long is a hang, default 10
+ *   hil.rolloverSeconds rollover duration, default 600 (past the 512 s wrap from any start)
+ *   hil.idleSeconds     idleStart: how long the link is left idle, default 60
+ *   hil.crc             off, 1 or 2; default: the driver's own default
+ *   hil.maxLossPercent  default 1.0
+ *   hil.outDir          where reports go, default build/hil
+ * 
+ */ +public class JavaHilScenariosTest { + + private static final double GRAVITY = 9.81; + /** At 256 Hz a second without a packet is ~256 packets the gap count cannot see. */ + private static final double MAX_SILENCE_AT_END_MS = 1000; + /** + * How close the packet after a one-sample gap must arrive to a decoded battery reply for the gap to + * count as the sample a Shimmer3 skips to send that reply (DEV-1297). Measured: 1-7 ms. + */ + private static final double BATTERY_REPLY_WINDOW_MS = 25; + /** + * The ACK/response timer's own line when a command gets no reply: "Command: [0x72] GET_STATUS_COMMAND + * timeout", or "[0x..]UNKNOWN" for an opcode the driver doesn't know. + */ + private static final java.util.regex.Pattern COMMAND_TIMEOUT = java.util.regex.Pattern.compile("Command:\t\\[0x[0-9A-F]{2}\\] ?\\S+ timeout"); + /** The slowest start idleStart accepts after the wait, as the C# and shimmer-logandstream HILs do. */ + private static final double MAX_START_AFTER_IDLE_MS = 500; + /** The rates samplingRates writes in turn, as the shimmer-logandstream HIL's config.sampling_rate does. */ + private static final double[] SAMPLING_RATES_HZ = {51.2, 256, 512}; + + private HilSession session; + private HilReport report; + private HilShimmerPC device; + private int logStart; + + private static String arg(String name, String fallback) { + String v = System.getProperty("hil." + name); + return v == null || v.isEmpty() ? fallback : v; + } + + private static double arg(String name, double fallback) { + return Double.parseDouble(arg(name, Double.toString(fallback))); + } + + private static int arg(String name, int fallback) { + return Integer.parseInt(arg(name, Integer.toString(fallback))); + } + + private void begin(String scenario) { + String port = arg("port", null); + assumeTrue("No unit given: pass -Phil.port=COMx (tools/hil/run-java-hil.ps1 does)", port != null); + String crc = arg("crc", null); + if (crc != null) { + ShimmerBluetooth.setDefaultBtCrcModeToUseIfFwSupported( + "off".equals(crc) ? BT_CRC_MODE.OFF : "1".equals(crc) ? BT_CRC_MODE.ONE_BYTE_CRC : BT_CRC_MODE.TWO_BYTE_CRC); + } + Map args = new LinkedHashMap<>(); + System.getProperties().stringPropertyNames().stream().filter(k -> k.startsWith("hil.")).sorted() + .forEach(k -> args.put(k.substring(4), System.getProperty(k))); + String mac = arg("mac", ""); + String type = arg("type", "Shimmer3"); + report = new HilReport(scenario, arg("unit", port), port, mac, type, args); + session = new HilSession(port, mac, type); + device = session.device; + logStart = device.logSize(); + } + + @After + public void end() { + if (session == null) { + return; + } + putDriverCounts(); + session.close(); + report.write(new File(arg("outDir", "build/hil")), session.events(), device.log()); + } + + private void finish() { + report.check(session.connectedBeforeReady == 0, session.connectedBeforeReady + " of " + session.connects + + " connects reported CONNECTED before the connect sequence ended (DEV-1275)"); + if (session.hung != null) { + report.put("hungCall", session.hung); + report.check(false, session.hung + " never returned: the API call blocked (thread dump in the report's events)"); + } + if (!report.failures().isEmpty()) { + Assert.fail(String.join("; ", report.failures())); + } + } + + /** What the driver did in this session: replies by type, decodes, timer requests, connects. */ + private void putDriverCounts() { + report.put("connects", session.connects); + report.put("connectedBeforeReady", session.connectedBeforeReady); + report.put("inStreamReplies", device.inStreamReplies()); + report.put("statusesDecoded", device.statusesDecoded()); + report.put("batteryReadings", device.batteryReadings()); + report.put("statusRequests", device.countSince(logStart, "GET_STATUS_COMMAND Instruction added")); + report.put("commandTimeouts", device.countSince(logStart, COMMAND_TIMEOUT)); + } + + // --- shared checks ------------------------------------------------------------------------- + + private boolean connectAndConfigure(double rateHz) throws Exception { + if (!connectAndDescribe()) { + return false; + } + boolean configured = session.configureAccelOnly(rateHz, 20000); + report.put("rateOnDeviceHz", device.getSamplingRateShimmer()); + report.check(configured, "configuration did not complete within 20 s (state " + session.state() + ")"); + return configured; + } + + /** Connects, and records what the unit is: its hardware, firmware and the link CRC in use. */ + private boolean connectAndDescribe() throws Exception { + long start = System.currentTimeMillis(); + boolean connected = session.connect(30000); + report.put("connectMs", System.currentTimeMillis() - start); + report.check(connected, String.valueOf(session.connectFailure)); + if (!connected) { + return false; + } + report.put("hardware", device.getHardwareVersionParsed()); + report.put("firmware", device.getFirmwareVersionParsed()); + report.put("crcMode", String.valueOf(device.getCurrentBtCommsCrcMode())); + return true; + } + + /** The driver says the link has gone: lost, or closed under the test. */ + private boolean linkLost() { + BT_STATE s = session.state(); + return s == BT_STATE.CONNECTION_LOST || s == BT_STATE.DISCONNECTED; + } + + /** Accel at rest: NaN fails too, since the scenario configured the accel. */ + private void checkAccelAtRest(StreamAnalysis a) { + report.check(Math.abs(a.accelMagnitudeMean - GRAVITY) <= 1.0, String.format(Locale.ROOT, + "accel at rest %.3f m/s^2, expected %.2f±1.00 (NaN: no calibrated accel; otherwise is the unit lying still?)", + a.accelMagnitudeMean, GRAVITY)); + } + + private void checkRate(double deviceRateHz, String what) { + report.check(!Double.isNaN(deviceRateHz) && deviceRateHz > 0, + what + ": the API has no sampling rate for the unit (" + deviceRateHz + " Hz)"); + } + + private void checkStream(StreamAnalysis a, List samples, double stoppedAtMs, + double maxLossPercent, double deviceRateHz, String what) { + report.check(a.received > 0, what + ": no packets received"); + report.check(a.lossPercent() <= maxLossPercent, String.format(Locale.ROOT, + "%s: %.3f%% packets lost (%d of %d), limit %.2f%%", what, a.lossPercent(), a.missing, + a.received + a.missing, maxLossPercent)); + report.check(a.nonIncreasing == 0, what + ": " + a.nonIncreasing + " timestamps did not increase"); + checkJumps(a, what); + checkTimeline(a, samples, stoppedAtMs, deviceRateHz, what); + } + + /** A device timestamp that leapt ahead of the arrival time is wrong data (DEV-1023 class), never loss. */ + private void checkJumps(StreamAnalysis a, String what) { + for (StreamAnalysis.Gap j : a.timestampJumps) { + report.check(false, String.format(Locale.ROOT, + "%s: timestamp jumped %.1f s ahead at %.0f ms (device time %.0f ms) while packets kept arriving", + what, (j.missing + 1) * a.expectedPeriodMs / 1000.0, j.afterReceivedMs, j.afterTimestampMs)); + } + } + + /** + * Loss is counted between packets received, so two things it cannot see are checked here: the + * timestamps must give a rate within 1 % of the configured one, and packets must have kept + * arriving until recording stopped. + */ + private void checkTimeline(StreamAnalysis a, List samples, double stoppedAtMs, + double deviceRateHz, String what) { + if (Double.isNaN(a.effectiveRateHz) || Double.isInfinite(a.effectiveRateHz)) { + report.check(false, what + ": no usable device timestamps to measure the rate from (" + a.received + " packets)"); + } else { + report.check(Math.abs(a.effectiveRateHz - deviceRateHz) <= 0.01 * deviceRateHz, String.format(Locale.ROOT, + "%s: effective rate %.2f Hz, device set to %.2f Hz", what, a.effectiveRateHz, deviceRateHz)); + } + if (!samples.isEmpty()) { + double silentMs = stoppedAtMs - samples.get(samples.size() - 1).receivedMs; + report.check(silentMs <= MAX_SILENCE_AT_END_MS, String.format(Locale.ROOT, + "%s: no packet in the last %.1f s before recording stopped (the stream went silent)", what, silentMs / 1000.0)); + } + } + + /** + * Judges a stream recorded in stretches, split where the test stopped and restarted streaming on + * purpose, so the pause is not taken for loss. Each stretch gets the timestamp checks. Each gap + * is charged, as StreamAnalysis.attribute() does, to the nearest SD logging stop or battery read + * within 1 s: + *
    + *
  • loss near an SD logging stop is reported, not failed (the unit pauses while it closes its + * file);
  • + *
  • a single sample skipped right where a battery reply was decoded is reported, not failed: a + * Shimmer3 gives up a sample slot to answer GET_VBATT mid-stream (DEV-1297). Had the driver lost + * that packet, it would have left bytes behind, which checkDriverLog() fails on;
  • + *
  • any other loss near a battery read, or more than maxLossPercent anywhere else, fails.
  • + *
+ */ + private void checkStretches(List> stretches, double stoppedAtMs, double deviceRateHz, + double maxLossPercent, List sdStops, List batteryMoments) { + int received = 0; + int missing = 0; + int nearSd = 0; + int nearBattery = 0; + int skippedAtBatteryReplies = 0; + double[] sd = toArray(sdStops); + double[] battery = toArray(batteryMoments); + double[] batteryReplies = toArray(device.batteryReplyTimesMs()); + List all = new ArrayList<>(); + List summaries = new ArrayList<>(); + for (int k = 0; k < stretches.size(); k++) { + List stretch = stretches.get(k); + String what = "stretch " + (k + 1); + all.addAll(stretch); + StreamAnalysis a = StreamAnalysis.analyse(stretch, deviceRateHz); + session.event(what + ": " + a); + summaries.add(what + ": " + a); + report.check(a.received > 0, what + ": no packets received"); + received += a.received; + missing += a.missing; + for (StreamAnalysis.Gap g : a.gaps) { + double toSd = distanceToNearest(sd, g.afterReceivedMs); + double toBattery = distanceToNearest(battery, g.afterReceivedMs); + if (Math.min(toSd, toBattery) > 1000) { + continue; + } + if (toSd <= toBattery) { + nearSd += g.missing; + } else if (g.missing == 1 && distanceToNearest(batteryReplies, g.afterReceivedMs) <= BATTERY_REPLY_WINDOW_MS) { + skippedAtBatteryReplies++; + } else { + nearBattery += g.missing; + } + } + report.check(a.nonIncreasing == 0, what + ": " + a.nonIncreasing + " timestamps did not increase"); + checkJumps(a, what); + // The rate needs a second or so of stream; only the last stretch can go silent before a stop + // the test did not make itself. + if (a.received >= deviceRateHz) { + double end = k == stretches.size() - 1 ? stoppedAtMs : stretch.get(stretch.size() - 1).receivedMs; + checkTimeline(a, stretch, end, deviceRateHz, what); + } + } + report.put("stretches", summaries); + report.put("received", received); + report.put("missing", missing); + report.put("missingNearSdLoggingStops", nearSd); + report.put("missingNearBatteryReads", nearBattery); + report.put("skippedAtBatteryReplies", skippedAtBatteryReplies); + report.samples(all); + if (nearSd > 0) { + session.event(nearSd + " packets not received within 1 s of an SD logging stop (firmware side; not failed)"); + } + if (skippedAtBatteryReplies > 0) { + session.event(skippedAtBatteryReplies + " single samples skipped where the unit sent a battery reply" + + " (firmware side, DEV-1297; not failed)"); + } + report.check(nearBattery == 0, nearBattery + " packets lost within 1 s of a battery read while streaming"); + int elsewhere = missing - nearSd - nearBattery - skippedAtBatteryReplies; + double elsewherePercent = 100.0 * elsewhere / Math.max(1, received + missing); + report.put("missingElsewhere", elsewhere); + report.check(elsewherePercent <= maxLossPercent, String.format(Locale.ROOT, + "stream: %.3f%% packets lost away from SD logging stops and battery reads (%d), limit %.2f%%", + elsewherePercent, elsewhere, maxLossPercent)); + } + + /** Parser errors and command timeouts the driver logged since index from. */ + private void checkDriverLog(int from, String what) { + int parserErrors = device.countSince(from, "Unknown parsing error", "Unknown packet error", "Throw Bytes"); + report.check(parserErrors == 0, what + ": " + parserErrors + " parser errors logged by the driver (see the .driver.log)"); + int timeouts = device.countSince(from, COMMAND_TIMEOUT); + report.check(timeouts == 0, what + ": " + timeouts + " command timeouts logged by the driver (see the .driver.log)"); + } + + private static double[] toArray(List values) { + double[] out = new double[values.size()]; + for (int i = 0; i < out.length; i++) { + out[i] = values.get(i); + } + return out; + } + + /** The distance from t to the nearest of the moments; infinite when there are none. */ + private static double distanceToNearest(double[] momentsMs, double t) { + double nearest = Double.POSITIVE_INFINITY; + for (double m : momentsMs) { + nearest = Math.min(nearest, Math.abs(t - m)); + } + return nearest; + } + + // --- scenarios ----------------------------------------------------------------------------- + + /** Connect, configure, stream at rest, stop, disconnect. */ + @Test + public void streamRest() throws Exception { + begin("stream_rest"); + double rate = arg("rate", 256.0); + int seconds = arg("seconds", 30); + double maxLoss = arg("maxLossPercent", 1.0); + if (connectAndConfigure(rate)) { + double deviceRate = device.getSamplingRateShimmer(); + checkRate(deviceRate, "stream"); + int logMark = device.logSize(); + session.startRecording(); + report.check(session.startStreaming(10000), "streaming did not start within 10 s"); + Thread.sleep(seconds * 1000L); + double stoppedAtMs = session.nowMs(); + List samples = session.stopRecording(); + report.check(session.stopStreaming(10000), "streaming did not stop within 10 s"); + StreamAnalysis a = StreamAnalysis.analyse(samples, deviceRate); + session.event("stream: " + a); + report.putStream("stream", a); + report.putGaps(a); + report.samples(samples); + checkStream(a, samples, stoppedAtMs, maxLoss, deviceRate, "stream"); + checkAccelAtRest(a); + checkDriverLog(logMark, "stream"); + report.check(session.disconnect(10000), "did not disconnect within 10 s"); + } + finish(); + } + + /** + * SD logging and battery reads on a streaming unit, in the order Consensys uses (DEV-436): SD + * logging starts with streaming stopped (stop streaming, SET_RWC and START_LOGGING_ONLY on the + * quiet link, stream again), stops mid-stream (STOP_LOGGING_ONLY), and the battery is read + * mid-stream. Each call and reply is waited on. Needs an SD card in the unit. + */ + @Test + public void midStreamSet() throws Exception { + begin("mid_stream_set"); + double rate = arg("rate", 256.0); + int cycles = arg("cycles", 3); + double maxLoss = arg("maxLossPercent", 1.0); + if (connectAndConfigure(rate)) { + double deviceRate = device.getSamplingRateShimmer(); + checkRate(deviceRate, "stream"); + int logMark = device.logSize(); + session.startRecording(); + report.check(session.startStreaming(10000), "streaming did not start within 10 s"); + Thread.sleep(3000); + List> stretches = new ArrayList<>(); + List sdStops = new ArrayList<>(); + List batteryMoments = new ArrayList<>(); + for (int i = 1; i <= cycles && session.hung == null; i++) { + String what = "cycle " + i; + session.event(what); + stretches.add(session.startSdLoggingLikeConsensys(what, report)); + Thread.sleep(2000); + sdStops.add(session.nowMs()); + boolean stopped = session.call("stopSDLogging", 10000, device::stopSDLogging); + report.check(stopped, what + ": stopSDLogging did not complete: it threw, hung or was skipped (see the events)"); + if (stopped) { + report.check(session.waitFor(() -> session.state() == BT_STATE.STREAMING, 5000), + what + ": SD logging did not stop (state " + session.state() + ")"); + } + Thread.sleep(1000); + batteryMoments.add(session.nowMs()); + int readingsBefore = device.batteryReadings(); + boolean asked = session.call("readBattery", 10000, device::readBattery); + report.check(asked, what + ": readBattery did not complete: it threw, hung or was skipped (see the events)"); + if (asked) { + report.check(session.waitFor(() -> device.batteryReadings() > readingsBefore, 5000), + what + ": no battery reply decoded within 5 s of readBattery"); + } + Thread.sleep(2000); + } + double stoppedAtMs = session.nowMs(); + stretches.add(session.stopRecording()); + report.check(session.stopStreaming(10000), "streaming did not stop within 10 s"); + checkStretches(stretches, stoppedAtMs, deviceRate, maxLoss, sdStops, batteryMoments); + checkDriverLog(logMark, "stream"); + report.check(session.disconnect(10000), "did not disconnect within 10 s"); + } + finish(); + } + + /** Connect, stream for 5 s and disconnect, repeatedly. Every connect starts the status timer. */ + @Test + public void reconnectLoop() throws Exception { + begin("reconnect_loop"); + double rate = arg("rate", 256.0); + int cycles = arg("cycles", 5); + double maxLoss = arg("maxLossPercent", 1.0); + List connectTimes = new ArrayList<>(); + for (int i = 1; i <= cycles && session.hung == null; i++) { + String what = "cycle " + i; + long start = System.currentTimeMillis(); + boolean ready = i == 1 ? connectAndConfigure(rate) : session.connect(30000); + connectTimes.add(System.currentTimeMillis() - start); + // In cycle 1 a failed configure is reported by connectAndConfigure, with connectFailure null + report.check(ready, what + ": " + (session.connectFailure != null ? session.connectFailure + : "not ready to stream (state " + session.state() + ")")); + if (!ready) { + break; + } + double deviceRate = device.getSamplingRateShimmer(); + checkRate(deviceRate, what); + int logMark = device.logSize(); + session.startRecording(); + report.check(session.startStreaming(10000), what + ": streaming did not start within 10 s"); + Thread.sleep(5000); + double stoppedAtMs = session.nowMs(); + List samples = session.stopRecording(); + report.check(session.stopStreaming(10000), what + ": streaming did not stop within 10 s"); + StreamAnalysis a = StreamAnalysis.analyse(samples, deviceRate); + session.event(what + " stream: " + a); + checkStream(a, samples, stoppedAtMs, maxLoss, deviceRate, what); + checkDriverLog(logMark, what); + report.check(session.disconnect(10000), what + ": did not disconnect within 10 s"); + Thread.sleep(2000); + } + report.put("connectMs", connectTimes); + finish(); + } + + /** + * In-stream commands while streaming. First each reply on its own: status (0x8A 0x71), directory + * (0x8A 0x88) and battery (0x8A 0x94), each checked to be decoded. Then the overlap, as Consensys + * meets it: with the unit streaming and logging (logging started the Consensys way), stop SD + * logging mid-stream (STOP_LOGGING_ONLY) and request status and battery at once, so in-stream + * replies, including any status the unit pushes as logging stops, arrive while that command waits + * for its ACK (DEV-1262). Every command must complete, with its own reply, and none may time out. + */ + @Test + public void inStream() throws Exception { + begin("in_stream"); + double rate = arg("rate", 256.0); + int rounds = arg("cycles", 3); + int overlaps = arg("overlaps", 5); + double maxLoss = arg("maxLossPercent", 1.0); + if (connectAndConfigure(rate)) { + double deviceRate = device.getSamplingRateShimmer(); + checkRate(deviceRate, "stream"); + int logMark = device.logSize(); + session.startRecording(); + report.check(session.startStreaming(10000), "streaming did not start within 10 s"); + Thread.sleep(2000); + for (int i = 1; i <= rounds && session.hung == null; i++) { + String what = "round " + i; + int statusBefore = device.statusesDecoded(); + expectReply(what, "status", "STATUS", device::readStatusLogAndStream, () -> device.statusesDecoded() > statusBefore); + expectReply(what, "directory", "DIR", device::readDirectoryName, + () -> device.getDirectoryName() != null && !device.getDirectoryName().isEmpty()); + int batteryBefore = device.batteryReadings(); + expectReply(what, "battery", "VBATT", device::readBattery, () -> device.batteryReadings() > batteryBefore); + Thread.sleep(500); + } + List> stretches = new ArrayList<>(); + List sdStops = new ArrayList<>(); + for (int i = 1; i <= overlaps && session.hung == null; i++) { + String what = "overlap " + i; + stretches.add(session.startSdLoggingLikeConsensys(what, report)); + Thread.sleep(1000); + int statusReplies = device.inStreamReplies("STATUS"); + int batteryReplies = device.inStreamReplies("VBATT"); + int statusBefore = device.statusesDecoded(); + int batteryBefore = device.batteryReadings(); + int timeoutsBefore = device.countSince(logMark, COMMAND_TIMEOUT); + sdStops.add(session.nowMs()); + boolean sent = session.call(what + ": STOP_LOGGING_ONLY, GET_STATUS and GET_VBATT back to back", 10000, () -> { + device.stopSDLogging(); + device.readStatusLogAndStream(); + device.readBattery(); + }); + report.check(sent, what + ": the three calls did not complete (see the events)"); + if (sent) { + boolean done = session.waitFor(() -> device.inStreamReplies("STATUS") > statusReplies + && device.inStreamReplies("VBATT") > batteryReplies + && session.queuedInstructions() == 0 && session.state() == BT_STATE.STREAMING, 5000); + report.check(done, String.format(Locale.ROOT, + "%s: not every command completed within 5 s (status replies +%d, battery replies +%d, %d still queued, state %s)", + what, device.inStreamReplies("STATUS") - statusReplies, device.inStreamReplies("VBATT") - batteryReplies, + session.queuedInstructions(), session.state())); + report.check(device.statusesDecoded() > statusBefore, what + ": the status reply was not decoded"); + report.check(device.batteryReadings() > batteryBefore, what + ": the battery reply was not decoded"); + int timeouts = device.countSince(logMark, COMMAND_TIMEOUT) - timeoutsBefore; + report.check(timeouts == 0, what + ": " + timeouts + " command timeouts (a reply matched to the wrong command?)"); + } + Thread.sleep(1000); + } + double stoppedAtMs = session.nowMs(); + stretches.add(session.stopRecording()); + report.check(session.stopStreaming(10000), "streaming did not stop within 10 s"); + report.check(session.waitFor(() -> session.state() == BT_STATE.CONNECTED, 3000), + "after streaming the unit is " + session.state() + ", not CONNECTED"); + checkStretches(stretches, stoppedAtMs, deviceRate, maxLoss, sdStops, new ArrayList<>()); + checkDriverLog(logMark, "stream"); + report.check(session.disconnect(10000), "did not disconnect within 10 s"); + } + finish(); + } + + /** Sends one in-stream request and checks its reply both arrived and was decoded within 3 s. */ + private void expectReply(String round, String what, String replyType, HilSession.Call request, + HilSession.Condition decoded) throws InterruptedException { + int before = device.inStreamReplies(replyType); + if (!session.call(round + ": request " + what, 10000, request)) { + report.check(false, round + ": the " + what + " request did not complete (see the events)"); + return; + } + boolean arrived = session.waitFor(() -> device.inStreamReplies(replyType) > before, 3000); + report.check(arrived, round + ": no in-stream " + what + " reply within 3 s"); + if (arrived) { + report.check(session.waitFor(decoded, 1000), round + ": the " + what + " reply arrived but was not decoded"); + } + } + + /** + * DEV-1266 on hardware, with no SD logging. While streaming, app threads queue harmless reads + * (GET_VBATT_COMMAND and GET_STATUS_COMMAND) in tight loops, and check the queue length between + * them. Each of those calls locks the device and then the instruction list, so one is nearly + * always under way while the IO thread, holding the list, fetches the next instruction. That is + * the window the lock inversion needs. The queue is kept short so the unit is not flooded. + *

+ * Fails if the threads and the replies stop for hil.stallSeconds (default 10), or if the JVM + * finds a deadlock. The events then hold every thread's stack. Without the DEV-1266 fix (#334) a + * Shimmer3R deadlocked within 0.3 s in every run; with it, 60 s ran clean. + */ + @Test + public void queueStress() throws Exception { + begin("queue_stress"); + double rate = arg("rate", 256.0); + int threads = arg("threads", 4); + int seconds = arg("stressSeconds", 60); + int maxQueued = arg("maxQueued", 8); + int stallSeconds = arg("stallSeconds", 10); + if (connectAndConfigure(rate)) { + report.check(session.startStreaming(10000), "streaming did not start within 10 s"); + java.util.concurrent.atomic.AtomicLong calls = new java.util.concurrent.atomic.AtomicLong(); + java.util.concurrent.atomic.AtomicBoolean stop = new java.util.concurrent.atomic.AtomicBoolean(); + List workers = new ArrayList<>(); + for (int t = 0; t < threads; t++) { + Thread worker = new Thread(() -> { + while (!stop.get()) { + if (device.queuedInstructions() < maxQueued) { + if (calls.incrementAndGet() % 2 == 0) { + device.readBattery(); + } else { + device.readStatusLogAndStream(); + } + } else { + Thread.yield(); + } + } + }, "HilStress-" + t); + worker.setDaemon(true); + workers.add(worker); + } + session.event("queueStress: " + threads + " threads for up to " + seconds + " s, at most " + maxQueued + " queued"); + long start = System.nanoTime(); + workers.forEach(Thread::start); + long lastCalls = -1; + int lastReplies = -1; + long lastProgress = System.nanoTime(); + String hang = null; + while (System.nanoTime() - start < seconds * 1_000_000_000L) { + Thread.sleep(250); + long[] deadlocked = java.lang.management.ManagementFactory.getThreadMXBean().findDeadlockedThreads(); + if (deadlocked != null) { + hang = "the JVM found a deadlock"; + break; + } + long c = calls.get(); + int replies = device.statusesDecoded() + device.batteryReadings(); + if (c != lastCalls || replies != lastReplies) { + lastCalls = c; + lastReplies = replies; + lastProgress = System.nanoTime(); + } else if (System.nanoTime() - lastProgress > stallSeconds * 1_000_000_000L) { + hang = "no call returned and no reply arrived for " + stallSeconds + " s"; + break; + } + } + double ranSeconds = (System.nanoTime() - start) / 1e9; + stop.set(true); + for (Thread worker : workers) { + worker.join(5000); + } + report.put("stressSeconds", Math.round(ranSeconds * 10) / 10.0); + report.put("stressCalls", calls.get()); + report.put("stressReplies", device.statusesDecoded() + device.batteryReadings()); + if (hang == null && workers.stream().anyMatch(Thread::isAlive)) { + hang = "the stress threads did not stop"; + } + if (hang != null) { + session.hung = "queueStress"; + session.event("queueStress hung after " + String.format(Locale.ROOT, "%.1f", ranSeconds) + " s: " + hang + + "; every thread:\n" + com.shimmerresearch.shimmer3.communication.ByteCommunicationTestUtils.dumpAllThreads()); + report.check(false, String.format(Locale.ROOT, "hung after %.1f s and %d calls: %s (thread dump in the events)", + ranSeconds, calls.get(), hang)); + } else { + session.event(String.format(Locale.ROOT, "queueStress: %d calls, %d replies decoded in %.1f s, no hang", + calls.get(), device.statusesDecoded() + device.batteryReadings(), ranSeconds)); + report.check(session.waitFor(() -> session.queuedInstructions() == 0, 10000), "the queue did not drain after the stress"); + report.check(session.stopStreaming(10000), "streaming did not stop within 10 s"); + report.check(session.disconnect(10000), "did not disconnect within 10 s"); + } + } + finish(); + } + + /** + * Streams for 10 minutes (hil.rolloverSeconds), past the 512 s wrap of the unit's 3-byte + * timestamp counter from wherever it starts, as the C# HIL's stream.rollover does. The driver's + * unwrap must carry the timeline straight across the wrap: DEV-1023 was that rule, wrong the same + * way in four APIs. Fails on the stream checks, or if the raw counter never wrapped. + */ + @Test + public void rollover() throws Exception { + begin("rollover"); + double rate = arg("rate", 256.0); + int seconds = arg("rolloverSeconds", 600); + double maxLoss = arg("maxLossPercent", 1.0); + if (connectAndConfigure(rate)) { + double deviceRate = device.getSamplingRateShimmer(); + checkRate(deviceRate, "stream"); + int logMark = device.logSize(); + session.startRecording(); + report.check(session.startStreaming(10000), "streaming did not start within 10 s"); + // Watched each second, so a lost link ends the wait instead of sitting out the 10 minutes + long start = System.nanoTime(); + while (System.nanoTime() - start < seconds * 1_000_000_000L && !linkLost()) { + Thread.sleep(1000); + } + double streamedSeconds = (System.nanoTime() - start) / 1e9; + double stoppedAtMs = session.nowMs(); + List samples = session.stopRecording(); + int wraps = TimestampWraps.count(session.rawTicksRecorded()); + report.put("streamedSeconds", Math.round(streamedSeconds * 10) / 10.0); + report.put("counterWraps", wraps); + boolean lost = linkLost(); + report.check(!lost, String.format(Locale.ROOT, "the link was lost %.0f s into the stream (state %s)", streamedSeconds, session.state())); + if (!lost) { + report.check(session.stopStreaming(10000), "streaming did not stop within 10 s"); + } + StreamAnalysis a = StreamAnalysis.analyse(samples, deviceRate); + session.event("stream: " + a + "; the unit's counter wrapped " + wraps + " time(s)"); + report.putStream("stream", a); + report.putGaps(a); + report.samples(samples); + checkStream(a, samples, stoppedAtMs, maxLoss, deviceRate, "stream"); + report.check(wraps >= 1, String.format(Locale.ROOT, + "the unit's counter did not wrap in %.0f s of streaming, so the stream never crossed the 512 s wrap", streamedSeconds)); + checkAccelAtRest(a); + checkDriverLog(logMark, "stream"); + if (!lost) { + report.check(session.disconnect(10000), "did not disconnect within 10 s"); + } + } + finish(); + } + + /** + * A link left idle, as an app's is between configuring a unit and starting it: 60 s + * (hil.idleSeconds) in which the test sends nothing, with the driver's timers running as they do + * in an app, then a 10 s stream. The link must survive the wait, the status timer's requests + * must be answered, and streaming must start within 500 ms of the call, as the C# and + * shimmer-logandstream HILs require: a Classic link left quiet otherwise answers its next command + * late. + */ + @Test + public void idleStart() throws Exception { + begin("idle_start"); + double rate = arg("rate", 256.0); + int idleSeconds = arg("idleSeconds", 60); + double maxLoss = arg("maxLossPercent", 1.0); + if (connectAndConfigure(rate)) { + double deviceRate = device.getSamplingRateShimmer(); + checkRate(deviceRate, "stream"); + int idleMark = device.logSize(); + session.event("idle for " + idleSeconds + " s: timers " + device.timers()); + long idleStarted = System.nanoTime(); + while (System.nanoTime() - idleStarted < idleSeconds * 1_000_000_000L && !linkLost()) { + Thread.sleep(200); + } + double idled = (System.nanoTime() - idleStarted) / 1e9; + int statusRequests = device.countSince(idleMark, "GET_STATUS_COMMAND Instruction added"); + report.put("idleSeconds", Math.round(idled * 10) / 10.0); + report.put("statusRequestsWhileIdle", statusRequests); + session.event(String.format(Locale.ROOT, "idle %.0f s: %d status requests by the driver, timers %s", idled, statusRequests, device.timers())); + boolean lost = linkLost(); + report.check(!lost, String.format(Locale.ROOT, "the link was lost %.0f s into the idle wait (state %s)", idled, session.state())); + if (!lost) { + checkDriverLog(idleMark, "idle"); + int logMark = device.logSize(); + session.startRecording(); + long asked = System.nanoTime(); + boolean started = session.startStreaming(10000); + double startMs = (System.nanoTime() - asked) / 1e6; + report.put("startMs", Math.round(startMs)); + session.event(String.format(Locale.ROOT, "streaming %s %.0f ms after startStreaming", started ? "started" : "had not started", startMs)); + report.check(started, "streaming did not start within 10 s after the idle wait"); + report.check(!started || startMs <= MAX_START_AFTER_IDLE_MS, String.format(Locale.ROOT, + "streaming started %.0f ms after startStreaming, over %.0f ms", startMs, MAX_START_AFTER_IDLE_MS)); + Thread.sleep(10000); + double stoppedAtMs = session.nowMs(); + List samples = session.stopRecording(); + report.check(session.stopStreaming(10000), "streaming did not stop within 10 s"); + StreamAnalysis a = StreamAnalysis.analyse(samples, deviceRate); + session.event("stream: " + a); + report.putStream("stream", a); + report.putGaps(a); + report.samples(samples); + checkStream(a, samples, stoppedAtMs, maxLoss, deviceRate, "stream"); + checkAccelAtRest(a); + checkDriverLog(logMark, "stream"); + report.check(session.disconnect(10000), "did not disconnect within 10 s"); + } + } + finish(); + } + + /** + * Writes 51.2, 256 and 512 Hz in turn, each the way Consensys's Bluetooth manager writes a + * configuration (configureAccelOnly), and streams 5 s at each: the unit must stream at the rate + * it was given, as the shimmer-logandstream HIL's config.sampling_rate checks. Then the unit's own + * rate is written back. The unit is left accel only, as every scenario leaves it. + */ + @Test + public void samplingRates() throws Exception { + begin("sampling_rates"); + double maxLoss = arg("maxLossPercent", 1.0); + if (connectAndDescribe()) { + double ownRate = device.getSamplingRateShimmer(); + report.put("ownRateHz", ownRate); + List streams = new ArrayList<>(); + for (double rate : SAMPLING_RATES_HZ) { + if (session.hung != null) { + break; + } + String what = String.format(Locale.ROOT, "%.1f Hz", rate); + boolean configured = session.configureAccelOnly(rate, 20000); + report.check(configured, String.format(Locale.ROOT, "%s: the configuration did not take within 20 s (rate on device %.2f Hz, state %s)", + what, device.getSamplingRateShimmer(), session.state())); + if (!configured) { + continue; + } + double deviceRate = device.getSamplingRateShimmer(); + int logMark = device.logSize(); + session.startRecording(); + report.check(session.startStreaming(10000), what + ": streaming did not start within 10 s"); + Thread.sleep(5000); + double stoppedAtMs = session.nowMs(); + List samples = session.stopRecording(); + report.check(session.stopStreaming(10000), what + ": streaming did not stop within 10 s"); + StreamAnalysis a = StreamAnalysis.analyse(samples, deviceRate); + session.event(what + " stream: " + a); + streams.add(what + ": " + a); + checkStream(a, samples, stoppedAtMs, maxLoss, deviceRate, what); + checkDriverLog(logMark, what); + } + report.put("streams", streams); + if (session.hung == null) { + boolean restored = session.configureAccelOnly(ownRate, 20000); + report.check(restored, String.format(Locale.ROOT, "the unit's own rate, %.2f Hz, was not written back (rate on device %.2f Hz)", + ownRate, device.getSamplingRateShimmer())); + report.put("rateOnDeviceHz", device.getSamplingRateShimmer()); + } + report.check(session.disconnect(10000), "did not disconnect within 10 s"); + } + finish(); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/StreamAnalysis.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/StreamAnalysis.java new file mode 100644 index 000000000..85154a618 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/StreamAnalysis.java @@ -0,0 +1,196 @@ +package com.shimmerresearch.hil; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Locale; + +/** + * Judges a recorded stream from the device timestamps alone. The checks mirror the firmware HIL + * harness in log-and-stream-common Test/hil (DEV-1165): packet loss and non-increasing timestamps + * from the driver's already-unwrapped timestamps, the effective sample rate, and accel at rest. + * Pure Java, so it is unit-tested on the JVM (StreamAnalysisTest, in the normal test task). + *

+ * The same class as the Android HIL's (ShimmerAndroidAPI, shimmerHilTest), so both judge a stream + * by the same rules; a change here belongs there too. + */ +public final class StreamAnalysis { + + /** One received packet. Times in ms; accel in m/s^2, NaN when the channel is absent. */ + public static final class Sample { + public final double receivedMs; + public final double timestampMs; + public final double accelX, accelY, accelZ; + + public Sample(double receivedMs, double timestampMs, double accelX, double accelY, double accelZ) { + this.receivedMs = receivedMs; + this.timestampMs = timestampMs; + this.accelX = accelX; + this.accelY = accelY; + this.accelZ = accelZ; + } + + double accelMagnitude() { + return Math.sqrt(accelX * accelX + accelY * accelY + accelZ * accelZ); + } + } + + /** A run of packets missing between two received ones. */ + public static final class Gap { + public final double afterTimestampMs; + public final double afterReceivedMs; + public final int missing; + + Gap(double afterTimestampMs, double afterReceivedMs, int missing) { + this.afterTimestampMs = afterTimestampMs; + this.afterReceivedMs = afterReceivedMs; + this.missing = missing; + } + } + + public final int received; + public final int missing; + public final int nonIncreasing; + /** + * Steps where the device timestamp leapt far ahead of the arrival time: not lost packets but a + * bad timestamp, such as a 24-bit wrap unwrapped wrongly (512 s at a 32768 Hz clock, DEV-1023). + */ + public final List timestampJumps; + public final double expectedPeriodMs; + public final double effectiveRateHz; + public final double accelMagnitudeMean; + public final double accelMagnitudeStd; + public final List gaps; + + private StreamAnalysis(int received, int missing, int nonIncreasing, List timestampJumps, double expectedPeriodMs, + double effectiveRateHz, double accelMagnitudeMean, double accelMagnitudeStd, List gaps) { + this.received = received; + this.missing = missing; + this.nonIncreasing = nonIncreasing; + this.timestampJumps = timestampJumps; + this.expectedPeriodMs = expectedPeriodMs; + this.effectiveRateHz = effectiveRateHz; + this.accelMagnitudeMean = accelMagnitudeMean; + this.accelMagnitudeStd = accelMagnitudeStd; + this.gaps = gaps; + } + + /** + * @param samples in arrival order + * @param rateHz the sampling rate the device was configured with + */ + public static StreamAnalysis analyse(List samples, double rateHz) { + double period = 1000.0 / rateHz; + int missing = 0; + int nonIncreasing = 0; + // The effective rate counts sample periods over device time, from ordinary steps only: a + // jump or a step backwards says nothing about the rate. + double periods = 0, spanMs = 0; + List gaps = new ArrayList<>(); + List jumps = new ArrayList<>(); + for (int i = 1; i < samples.size(); i++) { + double step = samples.get(i).timestampMs - samples.get(i - 1).timestampMs; + double arrivalStep = samples.get(i).receivedMs - samples.get(i - 1).receivedMs; + if (step <= 0) { + nonIncreasing++; + } else if (step > 1.5 * period) { + int lost = (int) Math.round(step / period) - 1; + Gap g = new Gap(samples.get(i - 1).timestampMs, samples.get(i - 1).receivedMs, lost); + // Packets really lost leave a pause in arrival about as long as the gap. A timestamp that + // leaps a second or more beyond the arrival time is a bad timestamp, not lost data. + if (step - arrivalStep > JUMP_MS) { + jumps.add(g); + } else { + missing += lost; + gaps.add(g); + periods += lost + 1; + spanMs += step; + } + } else { + periods += 1; + spanMs += step; + } + } + double effectiveRate = spanMs > 0 ? periods * 1000.0 / spanMs : Double.NaN; + double sum = 0, sumSq = 0; + int n = 0; + for (Sample s : samples) { + double m = s.accelMagnitude(); + if (!Double.isNaN(m)) { + sum += m; + sumSq += m * m; + n++; + } + } + double mean = n > 0 ? sum / n : Double.NaN; + double std = n > 1 ? Math.sqrt(Math.max(0, (sumSq - n * mean * mean) / (n - 1))) : Double.NaN; + return new StreamAnalysis(samples.size(), missing, nonIncreasing, jumps, period, effectiveRate, mean, std, gaps); + } + + /** How far ahead of the arrival time a timestamp must leap to count as a jump, not loss. */ + static final double JUMP_MS = 1000; + + /** + * Charges each gap to the kind of command nearest to it (by arrival time), if one is within + * windowMs. Commands that follow each other closely therefore never share a loss. + * + * @param momentsByKind moments (ms) of each kind of command + * @return packets lost per kind, in the same order + */ + public int[] attribute(double[][] momentsByKind, double windowMs) { + int[] lost = new int[momentsByKind.length]; + for (Gap g : gaps) { + int nearestKind = -1; + double nearest = Double.MAX_VALUE; + for (int k = 0; k < momentsByKind.length; k++) { + for (double t : momentsByKind[k]) { + double d = Math.abs(g.afterReceivedMs - t); + if (d < nearest) { + nearest = d; + nearestKind = k; + } + } + } + if (nearestKind >= 0 && nearest <= windowMs) { + lost[nearestKind] += g.missing; + } + } + return lost; + } + + /** Packets lost within windowMs (by arrival time) of any of the given moments. */ + public int missingNear(double[] momentsMs, double windowMs) { + int total = 0; + for (Gap g : gaps) { + for (double t : momentsMs) { + if (Math.abs(g.afterReceivedMs - t) <= windowMs) { + total += g.missing; + break; + } + } + } + return total; + } + + public double lossPercent() { + int expected = received + missing; + return expected == 0 ? 0 : 100.0 * missing / expected; + } + + @Override + public String toString() { + return String.format(Locale.ROOT, + "received=%d missing=%d (%.3f%%) nonIncreasing=%d timestampJumps=%d effectiveRate=%.2fHz accel=%.3f±%.3f m/s^2 gaps=%s", + received, missing, lossPercent(), nonIncreasing, timestampJumps.size(), effectiveRateHz, + accelMagnitudeMean, accelMagnitudeStd, gapsSummary()); + } + + private String gapsSummary() { + int shown = Math.min(gaps.size(), 5); + String[] parts = new String[shown]; + for (int i = 0; i < shown; i++) { + parts[i] = String.format(Locale.ROOT, "%d@%.0fms", gaps.get(i).missing, gaps.get(i).afterReceivedMs); + } + return Arrays.toString(parts) + (gaps.size() > shown ? "+" + (gaps.size() - shown) : ""); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/StreamAnalysisTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/StreamAnalysisTest.java new file mode 100644 index 000000000..472366319 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/StreamAnalysisTest.java @@ -0,0 +1,102 @@ +package com.shimmerresearch.hil; + +import static org.junit.Assert.assertEquals; + +import java.util.ArrayList; +import java.util.List; + +import org.junit.Test; + +/** The HIL verdicts are only as good as this arithmetic, so it is checked without a phone. */ +public class StreamAnalysisTest { + + private static List stream(double rateHz, int count, int... droppedIndices) { + List samples = new ArrayList<>(); + double period = 1000.0 / rateHz; + outer: + for (int i = 0; i < count; i++) { + for (int d : droppedIndices) { + if (d == i) { + continue outer; + } + } + samples.add(new StreamAnalysis.Sample(i * period, 1000 + i * period, 0, 0, 9.81)); + } + return samples; + } + + @Test + public void cleanStreamHasNoLoss() { + StreamAnalysis a = StreamAnalysis.analyse(stream(256, 2560), 256); + assertEquals(2560, a.received); + assertEquals(0, a.missing); + assertEquals(0, a.nonIncreasing); + assertEquals(256, a.effectiveRateHz, 0.01); + assertEquals(9.81, a.accelMagnitudeMean, 1e-9); + } + + @Test + public void countsEachDroppedPacket() { + StreamAnalysis a = StreamAnalysis.analyse(stream(256, 1000, 100, 500, 501, 502), 256); + assertEquals(996, a.received); + assertEquals(4, a.missing); + assertEquals(2, a.gaps.size()); + assertEquals(256, a.effectiveRateHz, 0.01); + } + + @Test + public void attributesLossToTheMomentItHappened() { + StreamAnalysis a = StreamAnalysis.analyse(stream(100, 1000, 300), 100); + // Packet 300 is missing; packet 299 arrived at 2990 ms. + assertEquals(1, a.missingNear(new double[] {3000}, 500)); + assertEquals(0, a.missingNear(new double[] {9000}, 500)); + } + + @Test + public void chargesEachGapToTheNearestCommandOnly() { + // 100 Hz; packet 300 (arrives ~3000 ms) is missing. An SD stop at 2900 ms and a battery read + // at 3920 ms are both within 1 s of it: the SD stop is nearer, so it alone is charged. + StreamAnalysis a = StreamAnalysis.analyse(stream(100, 1000, 300), 100); + int[] lost = a.attribute(new double[][] {{2900}, {3920}}, 1000); + assertEquals(1, lost[0]); + assertEquals(0, lost[1]); + } + + @Test + public void chargesNothingOutsideTheWindow() { + StreamAnalysis a = StreamAnalysis.analyse(stream(100, 1000, 300), 100); + int[] lost = a.attribute(new double[][] {{5000}, {8000}}, 1000); + assertEquals(0, lost[0] + lost[1]); + } + + @Test + public void tellsABadTimestampFromLostPackets() { + // What a Shimmer3R did over BLE at an SD logging start: one packet stamped a 24-bit wrap + // (512 s) ahead while packets kept arriving on time, then the next one back on track. + List s = stream(256, 1000); + StreamAnalysis.Sample bad = s.get(500); + s.set(500, new StreamAnalysis.Sample(bad.receivedMs, bad.timestampMs + 512000, 0, 0, 9.81)); + StreamAnalysis a = StreamAnalysis.analyse(s, 256); + assertEquals(1, a.timestampJumps.size()); + assertEquals(0, a.missing); + assertEquals(1, a.nonIncreasing); + assertEquals(256, a.effectiveRateHz, 0.5); + } + + @Test + public void flagsTimestampsThatGoBackwards() { + List s = stream(100, 10); + s.add(5, new StreamAnalysis.Sample(45, 1000, 0, 0, 9.81)); + StreamAnalysis a = StreamAnalysis.analyse(s, 100); + assertEquals(1, a.nonIncreasing); + } + + @Test + public void toleratesJitterBelowHalfAPeriod() { + List s = new ArrayList<>(); + for (int i = 0; i < 100; i++) { + s.add(new StreamAnalysis.Sample(i * 10, 1000 + i * 10 + (i % 2 == 0 ? 0 : 4), 0, 0, 9.81)); + } + assertEquals(0, StreamAnalysis.analyse(s, 100).missing); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/TimestampWraps.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/TimestampWraps.java new file mode 100644 index 000000000..06493014a --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/TimestampWraps.java @@ -0,0 +1,39 @@ +package com.shimmerresearch.hil; + +import java.util.List; + +/** + * Counts how often the unit's own timestamp counter wrapped during a stream, from the raw ticks the + * driver passes on over Bluetooth (the TIMESTAMP channel's UNCAL format; CAL is the unwrapped + * time). The counter is 3 bytes at 32768 Hz on Shimmer3 and Shimmer3R, so it wraps every 2^24 + * ticks, 512 s. Pure Java, so it is unit-tested on the JVM (TimestampWrapsTest, in the normal test + * task). Kept apart from StreamAnalysis, which is the same class as the Android HIL's. + */ +final class TimestampWraps { + + /** The raw counter's range: 3 bytes. */ + static final double RANGE_TICKS = 1 << 24; + + private TimestampWraps() { + } + + /** + * Steps where the raw counter fell by more than half its range: a wrap. A smaller step back is + * not a wrap but a fault the stream checks already count (StreamAnalysis.nonIncreasing). A packet + * without ticks (NaN) is skipped, so the step is taken from the last one that had them. + */ + static int count(List rawTicks) { + int wraps = 0; + double previous = Double.NaN; + for (double ticks : rawTicks) { + if (Double.isNaN(ticks)) { + continue; + } + if (previous - ticks > RANGE_TICKS / 2) { + wraps++; + } + previous = ticks; + } + return wraps; + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/TimestampWrapsTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/TimestampWrapsTest.java new file mode 100644 index 000000000..dc4c28320 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/TimestampWrapsTest.java @@ -0,0 +1,48 @@ +package com.shimmerresearch.hil; + +import static org.junit.Assert.assertEquals; + +import java.util.ArrayList; +import java.util.List; + +import org.junit.Test; + +/** The rollover scenario's wrap count, checked without a unit. */ +public class TimestampWrapsTest { + + /** Raw 3-byte ticks at 256 Hz (128 ticks a sample) from startTicks, as the counter gives them. */ + private static List rawTicks(double startTicks, int count) { + List ticks = new ArrayList<>(); + for (int i = 0; i < count; i++) { + ticks.add((startTicks + i * 128.0) % TimestampWraps.RANGE_TICKS); + } + return ticks; + } + + @Test + public void countsNoWrapInAShortStream() { + assertEquals(0, TimestampWraps.count(rawTicks(1000, 2560))); + } + + @Test + public void countsTheWrapInTenMinutesWhereverTheStreamStarts() { + // 600 s at 256 Hz is 153,600 samples: one wrap from any start, two from one just before a wrap + assertEquals(1, TimestampWraps.count(rawTicks(0, 153600))); + assertEquals(1, TimestampWraps.count(rawTicks(TimestampWraps.RANGE_TICKS / 2, 153600))); + assertEquals(2, TimestampWraps.count(rawTicks(TimestampWraps.RANGE_TICKS - 1000, 153600))); + } + + @Test + public void aSmallStepBackIsNotAWrap() { + List ticks = rawTicks(5000000, 100); + ticks.set(50, ticks.get(49) - 1000); + assertEquals(0, TimestampWraps.count(ticks)); + } + + @Test + public void ignoresTicksTheDriverDidNotGive() { + List ticks = rawTicks(TimestampWraps.RANGE_TICKS - 640, 10); + ticks.set(4, Double.NaN); + assertEquals(1, TimestampWraps.count(ticks)); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3.java index 3a4de3a82..45ac4ec9d 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -30,31 +31,26 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3 extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mWaitTask; TaskCompletionSource mStreamingTask; ByteCommunicationSimulatorS3 mByteCommunicationSimulatorS3; @Before public void setUp() { mByteCommunicationSimulatorS3 = new ByteCommunicationSimulatorS3("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } @Test public void test001_testConnectandDisconnect() { mByteCommunicationSimulatorS3.setIsNewBMPSupported(false); - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); //Just to give time to connect to finish - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); @@ -88,16 +84,7 @@ public void test001_testConnectandDisconnect() { @Test public void test002_testConnectandDisconnect_NewBMPSupported() { mByteCommunicationSimulatorS3.setIsNewBMPSupported(true); - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - boolean result = mWaitTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3R.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3R.java index f04fa4111..5dd1e90b9 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3R.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3R.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -49,28 +50,23 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3R extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mWaitTask; ByteCommunicationSimulatorS3R mByteCommunicationSimulatorS3R; @Before public void setUp() { mByteCommunicationSimulatorS3R = new ByteCommunicationSimulatorS3R("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3R); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } @Test public void test001_testConnectandDisconnect() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS);//Just to give time to connect to finish - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); @@ -118,16 +114,7 @@ public void test001_testConnectandDisconnect() { @Test public void test002_ConnectandTestBMP390() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); @@ -159,16 +146,7 @@ public void test002_ConnectandTestBMP390() { @Test public void test003_ConnectandTestCalibParamRead() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); } @@ -214,16 +192,7 @@ public void test003_ConnectandTestCalibParamRead() { @Test public void test004_ConnectandTestDefaultLNAccelAndGyroCalibParam() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); } @@ -266,16 +235,7 @@ public void test004_ConnectandTestDefaultLNAccelAndGyroCalibParam() { @Test public void test005_ConnectandTestDefaultWRAccelCalibParam() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); } @@ -306,16 +266,7 @@ public void test005_ConnectandTestDefaultWRAccelCalibParam() { @Test public void test006_ConnectandTestDefaultMagCalibParam() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); } @@ -335,16 +286,7 @@ public void test006_ConnectandTestDefaultMagCalibParam() { @Test public void test007_ConnectandTestDefaultHighGAccelCalibParam() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); } @@ -363,16 +305,7 @@ public void test007_ConnectandTestDefaultHighGAccelCalibParam() { @Test public void test008_ConnectandTestDefaultAltMagCalibParam() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); } diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_CRC_Streaming.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_CRC_Streaming.java index 568d693c2..7cc1efbfe 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_CRC_Streaming.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_CRC_Streaming.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -29,34 +30,29 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3_CRC_Streaming extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mCalibrationTask; TaskCompletionSource mStreamingTask; ByteCommunicationSimulatorS3 mByteCommunicationSimulatorS3; @Before public void setUp() { mByteCommunicationSimulatorS3 = new ByteCommunicationSimulatorS3_streaming_instream_crc("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } ArrayList mListOJC; @Test public void test001_testStreaming() { mListOJC = new ArrayList(); mByteCommunicationSimulatorS3.setIsNewBMPSupported(false); - mCalibrationTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mCalibrationTask = new TaskCompletionSource<>(); - mStreamingTask = new TaskCompletionSource(); - try { - boolean result = mCalibrationTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + mStreamingTask = new TaskCompletionSource(); try { mDevice.startStreaming(); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming.java index fab8ec632..07adcec3e 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -29,34 +30,29 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3_Streaming extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mCalibrationTask; TaskCompletionSource mStreamingTask; ByteCommunicationSimulatorS3 mByteCommunicationSimulatorS3; @Before public void setUp() { mByteCommunicationSimulatorS3 = new ByteCommunicationSimulatorS3_streaming("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } ArrayList mListOJC; @Test public void test001_testStreaming() { mListOJC = new ArrayList(); mByteCommunicationSimulatorS3.setIsNewBMPSupported(false); - mCalibrationTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mCalibrationTask = new TaskCompletionSource<>(); - mStreamingTask = new TaskCompletionSource(); - try { - boolean result = mCalibrationTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + mStreamingTask = new TaskCompletionSource(); try { mDevice.startStreaming(); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check.java index 74bb8a4cb..430e7cb18 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -29,34 +30,29 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mCalibrationTask; TaskCompletionSource mStreamingTask; ByteCommunicationSimulatorS3 mByteCommunicationSimulatorS3; @Before public void setUp() { mByteCommunicationSimulatorS3 = new ByteCommunicationSimulatorS3_streaming_timestamp_contiguous_check("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } ArrayList mListOJC; @Test public void test001_testStreaming() { mListOJC = new ArrayList(); mByteCommunicationSimulatorS3.setIsNewBMPSupported(false); - mCalibrationTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mCalibrationTask = new TaskCompletionSource<>(); - mStreamingTask = new TaskCompletionSource(); - try { - boolean result = mCalibrationTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + mStreamingTask = new TaskCompletionSource(); try { mDevice.startStreaming(); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Fail.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Fail.java index 4bdc92711..5884c764e 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Fail.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Fail.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -30,34 +31,29 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Fail extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mCalibrationTask; TaskCompletionSource mStreamingTask; ByteCommunicationSimulatorS3 mByteCommunicationSimulatorS3; public static int CONTIGUOUS_TIMESTAMP_TICKS_LIMIT = (10*32768); @Before public void setUp() { mByteCommunicationSimulatorS3 = new ByteCommunicationSimulatorS3_streaming_timestamp_contiguous_check_fail("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } ArrayList mListOJC; @Test public void test001_testStreaming() { mListOJC = new ArrayList(); mByteCommunicationSimulatorS3.setIsNewBMPSupported(false); - mCalibrationTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mCalibrationTask = new TaskCompletionSource<>(); - mStreamingTask = new TaskCompletionSource(); - try { - boolean result = mCalibrationTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + mStreamingTask = new TaskCompletionSource(); try { mDevice.startStreaming(); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Overflow.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Overflow.java index a4f46feec..d8d93e0f2 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Overflow.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Overflow.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -29,34 +30,29 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3_Streaming_Contiguous_Check_Overflow extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mCalibrationTask; TaskCompletionSource mStreamingTask; ByteCommunicationSimulatorS3 mByteCommunicationSimulatorS3; @Before public void setUp() { mByteCommunicationSimulatorS3 = new ByteCommunicationSimulatorS3_streaming_timestamp_contiguous_check_overflow("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } ArrayList mListOJC; @Test public void test001_testStreaming() { mListOJC = new ArrayList(); mByteCommunicationSimulatorS3.setIsNewBMPSupported(false); - mCalibrationTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mCalibrationTask = new TaskCompletionSource<>(); - mStreamingTask = new TaskCompletionSource(); - try { - boolean result = mCalibrationTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + mStreamingTask = new TaskCompletionSource(); try { mDevice.startStreaming(); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes.java index 4b89df292..84b8bbd8a 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -29,34 +30,29 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mCalibrationTask; TaskCompletionSource mStreamingTask; ByteCommunicationSimulatorS3 mByteCommunicationSimulatorS3; @Before public void setUp() { mByteCommunicationSimulatorS3 = new ByteCommunicationSimulatorS3_streaming_with_improved_throw_bytes("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } ArrayList mListOJC; @Test public void test001_testStreaming() { mListOJC = new ArrayList(); mByteCommunicationSimulatorS3.setIsNewBMPSupported(false); - mCalibrationTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mCalibrationTask = new TaskCompletionSource<>(); - mStreamingTask = new TaskCompletionSource(); - try { - boolean result = mCalibrationTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + mStreamingTask = new TaskCompletionSource(); try { mDevice.startStreaming(); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes_2.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes_2.java index a5ed4bd21..da4b56f44 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes_2.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes_2.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -29,34 +30,29 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3_Streaming_Throw_Bytes_2 extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mCalibrationTask; TaskCompletionSource mStreamingTask; ByteCommunicationSimulatorS3 mByteCommunicationSimulatorS3; @Before public void setUp() { mByteCommunicationSimulatorS3 = new ByteCommunicationSimulatorS3_streaming_with_improved_throw_bytes_2("COM99"); - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(mByteCommunicationSimulatorS3); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } ArrayList mListOJC; @Test public void test001_testStreaming() { mListOJC = new ArrayList(); mByteCommunicationSimulatorS3.setIsNewBMPSupported(false); - mCalibrationTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mCalibrationTask = new TaskCompletionSource<>(); - mStreamingTask = new TaskCompletionSource(); - try { - boolean result = mCalibrationTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + mStreamingTask = new TaskCompletionSource(); try { mDevice.startStreaming(); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11.java index 352fb6060..054f13afe 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -28,26 +29,21 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3lns0_16_11 extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mWaitTask; @Before public void setUp() { - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(new ByteCommunicationSimulatorS3LNS0_16_11("COM99")); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } @Test public void test001_testConnectandDisconnect() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS); - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_bt_streaming.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_bt_streaming.java index 26851dbe5..d264c594a 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_bt_streaming.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_bt_streaming.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -28,26 +29,21 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_bt_streaming extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mWaitTask; @Before public void setUp() { - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(new ByteCommunicationSimulatorS3LNS0_16_11_w_sd_bt_streaming("COM99")); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } @Test public void test001_testConnectandDisconnect() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(5, TimeUnit.SECONDS); //Just to give time to connect to finish - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_only.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_only.java index 37fba3b78..4b40b8ba2 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_only.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_only.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -28,26 +29,21 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sd_only extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mWaitTask; @Before public void setUp() { - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(new ByteCommunicationSimulatorS3LNS0_16_11_w_sd_only("COM99")); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } @Test public void test001_testConnectandDisconnect() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS);//Just to give time to connect to finish - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_master.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_master.java index d849f02df..725719a8e 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_master.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_master.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -28,26 +29,21 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_master extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mWaitTask; @Before public void setUp() { - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(new ByteCommunicationSimulatorS3LNS0_16_11_w_sync_master("COM99")); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } @Test public void test001_testConnectandDisconnect() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS);//Just to give time to connect to finish - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_slave.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_slave.java index 9ef38ea74..75aff1e45 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_slave.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_slave.java @@ -1,4 +1,5 @@ package com.shimmerresearch.shimmer3.communication; +import org.junit.After; import org.junit.Before; import org.junit.BeforeClass; import org.junit.FixMethodOrder; @@ -28,26 +29,21 @@ @FixMethodOrder(MethodSorters.NAME_ASCENDING) // Test methods will be run in alphabetical order public class API_0000X_ByteCommunicationShimmer3lns0_16_11_w_sync_slave extends BasicProcessWithCallBack{ ShimmerPC mDevice; - TaskCompletionSource mWaitTask; @Before public void setUp() { - mDevice = new ShimmerPC("COM99"); + mDevice = ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer("COM99"); mDevice.setTestRadio(new ByteCommunicationSimulatorS3LNS0_16_11_w_sync_slave("COM99")); setWaitForData(mDevice); } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } @Test public void test001_testConnectandDisconnect() { - mWaitTask = new TaskCompletionSource(); - mDevice.connect("",""); - - mWaitTask = new TaskCompletionSource<>(); - try { - boolean result = mWaitTask.getTask().waitForCompletion(3, TimeUnit.SECONDS);//Just to give time to connect to finish - } catch (InterruptedException e) { - // TODO Auto-generated catch block - e.printStackTrace(); - } + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); if (!mDevice.isConnected()) { assert(false); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_00031_ConnectReadyAfterConnectSequenceTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_00031_ConnectReadyAfterConnectSequenceTest.java new file mode 100644 index 000000000..7bba6aab7 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/API_00031_ConnectReadyAfterConnectSequenceTest.java @@ -0,0 +1,107 @@ +package com.shimmerresearch.shimmer3.communication; + +import static org.junit.Assert.*; + +import java.util.ArrayList; +import java.util.List; + +import org.junit.After; +import org.junit.Before; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.pcDriver.ShimmerPC; + +/** + * DEV-1275: the connect sequence reads the unit's status part way through, and + * ShimmerPC.eventLogAndStreamStatusChanged() moved CONNECTING to CONNECTED on + * that reply. ShimmerDeviceCallbackAdapter marks every CONNECTED initialised, + * so an app waiting for CONNECTED and initialised was told the unit was ready + * while the rest of the sequence (battery, calibration dump, inquiry) was still + * queued. Whatever it did next went out in among that sequence: streaming + * started part way through it, and a configure cut the calibration dump short, + * which left a Shimmer3's accel NaN. The sequence's own end, inquiryDone() and + * then isReadyForStreaming(), is what moves CONNECTING to CONNECTED. + *

+ * No hardware: ByteCommunicationSimulatorS3 answers the whole connect sequence, + * the status read included. + */ +public class API_00031_ConnectReadyAfterConnectSequenceTest { + + private ShimmerPC mDevice; + private volatile boolean mStatusRead; + private volatile boolean mSequenceEnded; + /** What had happened when the state first became CONNECTED; null until then */ + private volatile Boolean mStatusReadAtFirstConnected; + private volatile Boolean mSequenceEndedAtFirstConnected; + private volatile List mQueuedAtFirstConnected; + + @Before + public void setUp() { + mDevice = new ShimmerPC("COM99") { + @Override + public void startTimerReadStatus() { + // As in ByteCommunicationTestUtils.newShimmerPCWithoutStatusTimer: only the + // connect sequence's own status read should run + } + + @Override + protected void eventLogAndStreamStatusChanged(byte currentCommand) { + mStatusRead = true; + super.eventLogAndStreamStatusChanged(currentCommand); + } + + @Override + protected void isReadyForStreaming() { + mSequenceEnded = true; + super.isReadyForStreaming(); + } + + @Override + public boolean setBluetoothRadioState(BT_STATE state) { + if(state==BT_STATE.CONNECTED && mSequenceEndedAtFirstConnected==null){ + mStatusReadAtFirstConnected = mStatusRead; + mSequenceEndedAtFirstConnected = mSequenceEnded; + List queued = new ArrayList<>(); + for(byte[] instruction:new ArrayList<>(getListofInstructions())){ + if(instruction!=null){ + queued.add(btCommandToString(instruction[0])); + } + } + mQueuedAtFirstConnected = queued; + } + return super.setBluetoothRadioState(state); + } + }; + mDevice.setTestRadio(new ByteCommunicationSimulatorS3("COM99")); + } + + @After + public void tearDown() { + mDevice.disconnectNoException(); + } + + @Test + public void theUnitIsReportedReadyOnlyOnceTheConnectSequenceHasEnded() { + ByteCommunicationTestUtils.connectAndWaitUntilInitialised(mDevice); + + assertNotNull("the state became CONNECTED", mSequenceEndedAtFirstConnected); + assertTrue("the connect sequence read the status before the end, so the case is covered", mStatusReadAtFirstConnected); + assertTrue("CONNECTED came only once the connect sequence had ended (inquiryDone, isReadyForStreaming); still queued: " + + mQueuedAtFirstConnected, mSequenceEndedAtFirstConnected); + // Every read of the unit's configuration (status, battery, calibration dump, + // inquiry) is answered. What may remain: the inquiry itself, still at the head + // while its reply is handled, and the RTC write that the status reply queues + // when the unit's clock is not set. That write runs before anything the app + // queues, so it never lands in a stream. + List allowed = new ArrayList<>(); + allowed.add(ShimmerBluetooth.btCommandToString(ShimmerObject.INQUIRY_COMMAND)); + allowed.add(ShimmerBluetooth.btCommandToString(ShimmerObject.SET_RWC_COMMAND)); + for(String queued:mQueuedAtFirstConnected){ + assertTrue("no read from the connect sequence is still queued at CONNECTED, but " + queued + " is (queued: " + + mQueuedAtFirstConnected + ")", allowed.contains(queued)); + } + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/ByteCommunicationSimulatorS3R.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/ByteCommunicationSimulatorS3R.java index 4d7151238..b9ec057d7 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/ByteCommunicationSimulatorS3R.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/ByteCommunicationSimulatorS3R.java @@ -24,7 +24,26 @@ protected void txShimmerVersion() { mBuffer.add((byte) 0x0A); } - @Override + /** + * A Shimmer3R's inquiry reply has 11 bytes of settings, with the channel count + * at index 9, so the Shimmer3 reply this class inherited never parsed: the + * inquiry timed out, and the tests only passed because a status reply part way + * through the connect sequence reported the unit ready first (DEV-1275). The + * settings match this simulator's InfoMem: the sampling rate, config setup + * bytes 0-3 from the first block and 4-6 from the second, then no channels + * and a buffer size of 1. + */ + @Override + protected void inquiryResponse() { + mBuffer.add((byte) 0xff); + mBuffer.add((byte) 0x02); + byte[] bytes = UtilShimmer.hexStringToByteArray("80024D9B0E080000000001"); + for (byte b:bytes) { + mBuffer.add(b); + } + } + + @Override protected void txFirmwareVersion() { mBuffer.add((byte) 0xff); mBuffer.add((byte) 0x2f); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/ByteCommunicationTestUtils.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/ByteCommunicationTestUtils.java new file mode 100644 index 000000000..69d9f203c --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/shimmer3/communication/ByteCommunicationTestUtils.java @@ -0,0 +1,110 @@ +package com.shimmerresearch.shimmer3.communication; + +import static org.junit.Assert.fail; + +import java.lang.management.LockInfo; +import java.lang.management.ManagementFactory; +import java.lang.management.MonitorInfo; +import java.lang.management.ThreadInfo; +import java.lang.management.ThreadMXBean; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.pcDriver.ShimmerPC; + +/** Shared helpers for the byte-communication simulator tests. */ +public class ByteCommunicationTestUtils { + + /** Generous on purpose: a connect to the simulator normally finishes in well under a second, + * but a loaded CI runner can stall it for several. Only a genuine hang should hit this. */ + public static final long CONNECT_TIMEOUT_MS = 30000; + + /** + * A ShimmerPC for the simulator tests whose periodic read-status timer never starts. + *

+ * The connect sequence unlocks the instruction stack and then starts that timer with no delay, + * so its first readStatusTask (which locks the device, then the instruction list) runs just as + * the IOThread takes the first post-connect instruction in ShimmerBluetooth.getInstruction() + * (which locks the list, then the device). When the two meet they deadlock and the connect never + * finishes. That hung these tests on Linux CI every time (DEV-1198). The driver is deliberately + * left as it is; the tests only lose the 5 s status poll, and the connect sequence still reads + * the status once. + */ + public static ShimmerPC newShimmerPCWithoutStatusTimer(String comPort) { + return new ShimmerPC(comPort) { + @Override + public void startTimerReadStatus() { + // Deliberately empty - see above + } + }; + } + + /** + * Connects and blocks until the device has finished its post-connect config read (infomem, + * calibration, etc.), i.e. isInitialised() is set and the state has moved to CONNECTED. + * isConnected() alone is not enough - it turns true before that read has run, so a fixed + * sleep made these tests flaky on slow runners. + */ + public static void connectAndWaitUntilInitialised(ShimmerPC device) { + device.connect("",""); + long deadline = System.currentTimeMillis() + CONNECT_TIMEOUT_MS; + while (!(device.isInitialised() && device.getBluetoothRadioState()==BT_STATE.CONNECTED)) { + if (System.currentTimeMillis() > deadline) { + // A hang here has so far only reproduced on CI, so print where every thread is + // before failing - the log is the only evidence there is. + System.out.println(dumpAllThreads()); + fail("Device did not finish initialising within " + CONNECT_TIMEOUT_MS + " ms (state: " + device.getBluetoothRadioState() + ")"); + } + try { + Thread.sleep(20); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + fail("Interrupted while waiting for the device to initialise"); + } + } + } + + /** Every thread's full stack with the monitors it holds and the lock it waits on, plus any + * deadlock the JVM can see. ThreadInfo.toString() stops at 8 frames, too few for the driver. */ + public static String dumpAllThreads() { + ThreadMXBean mxBean = ManagementFactory.getThreadMXBean(); + StringBuilder sb = new StringBuilder("==== Thread dump ====\n"); + + long[] deadlocked = mxBean.findDeadlockedThreads(); + if (deadlocked != null) { + sb.append("DEADLOCK between thread ids:"); + for (long id : deadlocked) { + sb.append(' ').append(id); + } + sb.append('\n'); + } + + for (ThreadInfo ti : mxBean.dumpAllThreads(true, true)) { + sb.append('"').append(ti.getThreadName()).append("\" id=").append(ti.getThreadId()) + .append(' ').append(ti.getThreadState()); + if (ti.getLockName() != null) { + sb.append(" on ").append(ti.getLockName()); + } + if (ti.getLockOwnerName() != null) { + sb.append(" owned by \"").append(ti.getLockOwnerName()).append("\" id=").append(ti.getLockOwnerId()); + } + sb.append('\n'); + + StackTraceElement[] stack = ti.getStackTrace(); + MonitorInfo[] monitors = ti.getLockedMonitors(); + for (int i = 0; i < stack.length; i++) { + sb.append("\tat ").append(stack[i]).append('\n'); + for (MonitorInfo mi : monitors) { + if (mi.getLockedStackDepth() == i) { + sb.append("\t- locked ").append(mi).append('\n'); + } + } + } + for (LockInfo li : ti.getLockedSynchronizers()) { + sb.append("\t- locked synchronizer ").append(li).append('\n'); + } + sb.append('\n'); + } + return sb.append("==== End of thread dump ====").toString(); + } + +} diff --git a/ShimmerLSL/build.gradle b/ShimmerLSL/build.gradle index 4227dc2c0..419de8816 100644 --- a/ShimmerLSL/build.gradle +++ b/ShimmerLSL/build.gradle @@ -39,7 +39,7 @@ publishing { repositories { maven { name = "GitHubPackages" - url = uri("https://maven.pkg.github.com/ShimmerEngineering/Shimmer-Java-Android-API") + url = uri("https://maven.pkg.github.com/ShimmerResearch/Shimmer-Java-Android-API") credentials { /* Create gradle.properties file in GRADLE_USER_HOME/.gradle/ (e.g. C:/Users/YourUsername/.gradle/) with the two lines listed below. Fill in your diff --git a/ShimmerPCBasicExamples/build.gradle b/ShimmerPCBasicExamples/build.gradle index e3b8eb351..213a64eab 100644 --- a/ShimmerPCBasicExamples/build.gradle +++ b/ShimmerPCBasicExamples/build.gradle @@ -22,7 +22,7 @@ repositories { } maven { name = "GitHubPackages" - url = uri("https://maven.pkg.github.com/ShimmerEngineering/Shimmer-Java-Android-API") + url = uri("https://maven.pkg.github.com/ShimmerResearch/Shimmer-Java-Android-API") credentials { /* Create gradle.properties file in GRADLE_USER_HOME/.gradle/ (e.g. C:/Users/YourUsername/.gradle/) with the two lines listed below. Fill in your diff --git a/tools/hil/README.md b/tools/hil/README.md new file mode 100644 index 000000000..d73eb49a5 --- /dev/null +++ b/tools/hil/README.md @@ -0,0 +1,146 @@ +# Java HIL: the Java driver on real Shimmers + +Hardware-in-the-loop tests of the Java driver (`ShimmerDriver` with `ShimmerDriverPC`). A PC connects +to real Shimmer3 and Shimmer3R units over their paired Bluetooth Classic serial ports, through the +same API Consensys and MATLAB use (`ShimmerPC`), **with the driver's timers on** as an app runs it. +One command builds the tests, runs every scenario on every unit, and prints pass or fail. + +```powershell +.\tools\hil\run-java-hil.ps1 +``` + +It exits 0 when everything passed, 1 when anything failed, errored, timed out or was skipped, and 2 +when the bench isn't set up. + +The CI tests run against byte simulators, and since DEV-1198 (#325, #326) with the status timer off. +This is where the driver meets real firmware, a real radio and its own timers. + +## Before every Java API release (the gate) + +**Release Java API** won't publish a commit that hasn't passed this on hardware. Each round: + +1. On the bench, on `master` with a clean working tree and every unit in the rig, run: + ```powershell + git checkout master; git pull + .\tools\hil\run-java-hil.ps1 -Report + ``` + With `-Report`, the result is posted to GitHub as the commit status **`java-hil`** on that commit: + passed or failed, with each unit's firmware. It refuses to report anything but the full gate run: + - every scenario, on at least one Shimmer3 and one Shimmer3R; + - the default rate, duration, link CRC and loss limit, and a fresh build (no `-SkipBuild`); + - a clean working tree, pushed. +2. Run **Release Java API**. It looks up that status for the commit it's releasing and stops before + building anything unless it passed. The release notes say what was tested. + +If anything merges after step 1, the commit changes, so test again. In an emergency, put a Jira key in +**hil_waiver** to release without a pass; the release notes record the waiver. Dry runs only warn. + +## What it tests + +| Scenario | What it does | Fails when | +|---|---|---| +| `streamRest` | Connects, writes an accel-only config at `-Rate` (default 256 Hz) the way Consensys's Bluetooth manager does, streams for `-Seconds` (default 30) with the unit lying still, then stops and disconnects. | It can't connect or configure; more than `-MaxLossPercent` (1 %) of packets are lost; a timestamp doesn't increase, or leaps more than a second ahead of when it arrived (a bad unwrap, not loss); the timestamps give no rate, or one more than 1 % off the configured rate; the stream goes silent for over a second before the test stops it; accel is more than 1 m/s² from 9.81; or the driver logs a parser error or a command timeout. | +| `midStreamSet` | On a streaming unit, three times: starts SD logging **the way Consensys does** (stop streaming, start logging on the quiet link, stream again; DEV-436), stops it mid-stream, and reads the battery mid-stream. | One of those calls fails, or a battery reply isn't decoded within 5 s; logging doesn't start or stop, or streaming doesn't come back; a packet is lost around a battery read, or more than `-MaxLossPercent` elsewhere (a single sample skipped right where the battery reply arrives is reported, not failed: a Shimmer3 gives up a sample slot to answer a battery read, DEV-1297); a timestamp fault in any stretch between restarts; or the driver logs a parser error or a command timeout. Packets missing around an SD logging stop are reported, not failed: the unit pauses while it closes its file. Needs an SD card in the unit. | +| `reconnectLoop` | Connects, streams for 5 s and disconnects, five times on the same `ShimmerPC`. Every connect starts the driver's status timer, which is when the DEV-1266 lock inversion is most likely. | Any cycle fails to connect within 30 s, loses packets, fails the timestamp checks, or the driver logs a parser error or command timeout. | +| `inStream` | While streaming: first each in-stream reply on its own, three rounds: status (`0x8A 0x71`), directory (`0x8A 0x88`) and battery (`0x8A 0x94`). Then five overlaps as Consensys meets them: with the unit streaming and logging (logging started the Consensys way), stop SD logging mid-stream and request status and battery at once, so in-stream replies, including any status the unit pushes as logging stops, arrive while that command waits for its ACK (DEV-1262). | A reply doesn't arrive within 3 s or isn't decoded; an overlap doesn't complete within 5 s (both replies decoded, logging stopped, the queue empty); the driver logs a command timeout; or the stream fails the checks above. | +| `queueStress` | While streaming, four app threads call `readBattery()` and `readStatusLogAndStream()` and check the queue length, in tight loops for 60 s, keeping the queue under 8. Each of those calls locks the device and then the instruction list, so one is nearly always under way while the IO thread fetches the next instruction. That is the window DEV-1266's lock inversion needs (#334). No SD logging is involved. | The calls and replies stop for 10 s, or the JVM finds a deadlock; the queue doesn't drain afterwards. Without the DEV-1266 fix a Shimmer3R deadlocked within 0.3 s in every run. | +| `rollover` | Configures as `streamRest` does and streams for 10 minutes with the unit lying still. That is past the 512 s wrap of the unit's 3-byte timestamp counter from wherever it starts, so the driver's unwrap has to carry the timeline across it (DEV-1023, the same rule wrong in four APIs). The C# HIL's `stream.rollover` does the same. | The stream fails `streamRest`'s checks, or the link is lost; the unit's raw counter never wrapped (counted from the TIMESTAMP channel's raw ticks, so a shortened run doesn't pass). | +| `idleStart` | Connects and configures, then leaves the link idle for 60 s, with the driver's timers running as they do in an app, before streaming 10 s. The C# and shimmer-logandstream HILs check the same: a Bluetooth Classic link left quiet otherwise answers its next command late. The report counts the status timer's requests during the wait. | The link is lost during the wait, or the driver logs a command timeout or parser error in it; streaming starts more than 500 ms after `startStreaming()`; or the stream fails `streamRest`'s checks. | +| `samplingRates` | Writes 51.2, 256 and 512 Hz in turn, each the way Consensys's Bluetooth manager writes a configuration, and streams 5 s at each, as the shimmer-logandstream HIL's `config.sampling_rate` does. Then it writes the unit's own rate back, accel only as every scenario leaves it. | A configuration doesn't take within 20 s, or the unit reads back another rate; a stream loses packets, fails the timestamp checks, or has a rate more than 1 % off the one written; the driver logs a parser error or command timeout; or the unit's own rate isn't written back. | + +Every API call runs under a watchdog. If one doesn't return within 10 s, the scenario stops, and its +events hold every thread's stack with the locks each holds and waits on, plus any deadlock the JVM +detects (DEV-1266). If the whole run still doesn't finish, the runner stops Gradle after +`-ScenarioTimeoutSeconds` (900) and records TIMEOUT. + +A connect is never retried. If the COM port can't be opened, the scenario fails and says why: +- **"Port busy"**: another program on this PC already has the port open: another HIL, Consensys, a + serial terminal. The unit is in use, so a retry would only produce results from a shared unit. +- **CONNECTION_FAILED** for any other reason: the unit is off, out of range, or connected to + another host such as a phone. + +Every connect, in every scenario, is also checked for DEV-1275: the first CONNECTED must come only after the driver's NOTIFICATION_SHIMMER_FULLY_INITIALIZED, which marks the end of its connect sequence. `connectedBeforeReady` counts the connects that broke this, and any one fails the scenario. + +Each report counts what the session covered: connects, in-stream replies by type, statuses and +battery readings decoded, the status timer's requests, and command timeouts. Its events also say +which driver timers were running after connect, after configure and while streaming. + +Starting SD logging mid-stream (`startSDLogging()` while streaming) writes the RTC mid-stream, which a Shimmer3R answers with out-of-order timestamps (DEV-1245). Consensys never does that, and neither do these scenarios. + +The stream checks are the Android HIL's (`StreamAnalysis`, the same class in ShimmerAndroidAPI's +`shimmerHilTest`), so the two judge a stream by the same rules. `StreamAnalysisTest` runs in CI, as +does `TimestampWrapsTest`, for the wrap count `rollover` relies on. + +### What it does not test + +- BLE: on the PC it goes through the gRPC BLE server (`ShimmerGRPC`); not in v1. +- Status the firmware pushes on its own (dock, undock, button press), which needs someone at the + bench; the managed USB hub in `bench-tools/hub` could do that later. +- The SD and file parsers, and the Android API's own Classic parser (the Android HIL covers that). + +## Choosing what to test + +| | Default | Option | +|---|---|---| +| Units | every unit in the rig file | `-Unit s3r-86f8` | +| Scenarios | all eight (`rollover` alone streams 10 minutes a unit) | `-Scenario inStream` | +| Sampling rate, stream duration | 256 Hz, 30 s | `-Rate 512`, `-Seconds 60` | +| Link CRC | the driver's default (1 byte) | `-Crc off`, `-Crc 2` | +| Pause between runs | 10 s | `-SettleSeconds 30` | +| Record the result for the release gate | no | `-Report` (full run on a clean, pushed commit only) | + +## One-time setup + +1. **Pair each unit with the PC** in Windows Settings → Bluetooth (PIN `1234`). Windows creates an + outgoing serial port for it; the script finds that port from the unit's MAC. +2. **Prepare each unit:** SD sync and Bluetooth disable off (either keeps Bluetooth off, DEV-1228), an + SD card in for `midStreamSet`, lying still during `streamRest`, `rollover` and `idleStart`. +3. **List the units:** copy `rig-java.example.json` to `rig-java.json` and fill in each name, MAC + and `type` (`Shimmer3` or `Shimmer3R`). Add `comPort` only to override the port the script finds. + That file is gitignored. +4. **The checkout's folder must be named `Shimmer-Java-Android-API`**, because + `ShimmerDriverPC/settings.gradle` finds its sibling projects by that name. In a worktree, make a + junction with that name and run the script through it: + ```powershell + New-Item -ItemType Junction -Path C:\wt\Shimmer-Java-Android-API -Target C:\wt\ + C:\wt\Shimmer-Java-Android-API\tools\hil\run-java-hil.ps1 + ``` +5. **JDK 11 or newer.** The script uses `JAVA_HOME` if it qualifies, otherwise the first one it finds + under Amazon Corretto, Eclipse Adoptium or Java in Program Files. + +**Nothing else may use the units during a run.** That includes Consensys, the Android HIL's phone, +and the other HILs that share this bench (C#, shimmer-logandstream). + +Only a second Classic connection is refused outright, as "Port busy". A second host connecting over +BLE is not: +- a Shimmer3R that is streaming over Classic accepts the BLE link; +- it runs the commands sent over BLE and replies down the Classic link, which corrupts this run's + stream; +- the BLE host sees no replies at all. + +On 2026-10-21 that is how two HILs sharing a unit produced a bug report about the unit locking up +after a radio switch (DEV-1276). + +## Output + +The run's folder, `tools/hil/out//`, holds: +- `summary.json` and the table the script prints; +- `reports/`, per scenario and unit: + - `_.json`: versions, the CRC mode in use, loss, rate, accel, the counts above, a + timeline of events and the failures; + - `.csv`: every sample; + - `.driver.log`: every line the driver logged, verbose or not; +- `*.console.txt` and `*.junit.xml`: Gradle's output and the JUnit result for each run; +- `build.log`. + +## Running one scenario by hand + +```powershell +cd C:\wt\Shimmer-Java-Android-API\ShimmerDriverPC +.\gradlew :hilTest --no-watch-fs --tests com.shimmerresearch.hil.JavaHilScenariosTest.inStream "-Phil.port=COM36" "-Phil.type=Shimmer3R" "-Phil.unit=s3r-86f8" +``` + +Every `-Phil.` reaches the tests as `hil.`; the names are listed in +`JavaHilScenariosTest`. Without `hil.port` every scenario is skipped, and the normal `test` task +leaves them out. `--no-watch-fs` matters when you edit through a worktree's real path but build +through the junction: Gradle's file watcher misses those edits and would run stale classes. diff --git a/tools/hil/rig-java.example.json b/tools/hil/rig-java.example.json new file mode 100644 index 000000000..8d62516d9 --- /dev/null +++ b/tools/hil/rig-java.example.json @@ -0,0 +1,6 @@ +{ + "units": [ + { "name": "s3-xxxx", "mac": "00:06:66:XX:XX:XX", "type": "Shimmer3" }, + { "name": "s3r-xxxx", "mac": "E8:EB:1B:XX:XX:XX", "type": "Shimmer3R" } + ] +} diff --git a/tools/hil/run-java-hil.ps1 b/tools/hil/run-java-hil.ps1 new file mode 100644 index 000000000..f2986fb88 --- /dev/null +++ b/tools/hil/run-java-hil.ps1 @@ -0,0 +1,234 @@ +<# +.SYNOPSIS +Runs the Java driver's hardware-in-the-loop (HIL) scenarios on every Shimmer in a rig file, over +the PC's paired Bluetooth serial ports, and prints a pass/fail table. Exits 1 if anything did not pass. + +.DESCRIPTION +One-time setup is in tools/hil/README.md: pair each unit with this PC, list it in +tools/hil/rig-java.json (copy rig-java.example.json), and check out the repository in a folder named +Shimmer-Java-Android-API (ShimmerDriverPC's settings.gradle finds its siblings by that name). + +.EXAMPLE +.\tools\hil\run-java-hil.ps1 +Every scenario on every unit. + +.EXAMPLE +.\tools\hil\run-java-hil.ps1 -Unit s3r-86f8 -Scenario inStream + +.EXAMPLE +.\tools\hil\run-java-hil.ps1 -Report +Before "Release Java API": the full run on this commit, recorded on GitHub as the commit status +"java-hil". The release refuses to publish a commit without a passing one. +#> +param( + [string]$Rig = (Join-Path $PSScriptRoot 'rig-java.json'), + [ValidateSet('streamRest', 'midStreamSet', 'reconnectLoop', 'inStream', 'queueStress', 'rollover', 'idleStart', 'samplingRates')] + [string[]]$Scenario = @('streamRest', 'midStreamSet', 'reconnectLoop', 'inStream', 'queueStress', 'rollover', 'idleStart', 'samplingRates'), + [string[]]$Unit, + [double]$Rate = 256, + [int]$Seconds = 30, + # Link CRC to ask for; by default the driver's own default, as an app gets it. + [ValidateSet('off', '1', '2')] + [string]$Crc, + [double]$MaxLossPercent = 1.0, + [switch]$SkipBuild, + [switch]$Report, + [int]$ScenarioTimeoutSeconds = 900, + # Pause between runs, so the unit has dropped the last link before the next connect. + [int]$SettleSeconds = 10 +) + +$ErrorActionPreference = 'Continue' +$repo = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path +$gradleRoot = Join-Path $repo 'ShimmerDriverPC' +$testClass = 'com.shimmerresearch.hil.JavaHilScenariosTest' + +function Fail([string]$message) { + Write-Host "ERROR: $message" -ForegroundColor Red + exit 2 +} + +# --- Rig ----------------------------------------------------------------------------------------- +if (-not (Test-Path $Rig)) { Fail "No rig file at $Rig. Copy rig-java.example.json to rig-java.json and list your units (README)." } +$rigData = Get-Content $Rig -Raw | ConvertFrom-Json +$units = @($rigData.units) +if ($Unit) { $units = @($units | Where-Object { $Unit -contains $_.name }) } +if ($units.Count -eq 0) { Fail "No units to test (rig: $Rig, -Unit: $Unit)." } + +# Each unit's outgoing Bluetooth serial port, from its MAC, unless the rig names one. +$ports = @{} +Get-CimInstance Win32_PnPEntity -Filter "PNPClass='Ports'" -ErrorAction SilentlyContinue | + Where-Object { $_.DeviceID -match 'BTHENUM' } | ForEach-Object { + $m = [regex]::Match($_.DeviceID, '&([0-9A-F]{12})_') + $p = [regex]::Match($_.Name, 'COM\d+') + if ($m.Success -and $p.Success -and $m.Groups[1].Value -ne '000000000000') { $ports[$m.Groups[1].Value] = $p.Value } + } +foreach ($u in $units) { + if (-not $u.type) { Fail "Unit $($u.name): give its type (Shimmer3 or Shimmer3R)." } + if (-not $u.comPort) { + $key = ($u.mac -replace '[:-]', '').ToUpper() + if (-not $ports.ContainsKey($key)) { Fail "Unit $($u.name) ($($u.mac)) is not paired with this PC: no Bluetooth serial port has its MAC. Pair it (README) or give comPort." } + $u | Add-Member -NotePropertyName comPort -NotePropertyValue $ports[$key] -Force + } +} + +# The release gate trusts this status, so only report a run that tested exactly this commit, with +# the gate's own settings: every scenario, both device types, defaults, a fresh build, clean tree. +$commit = $null +$githubRepo = $null +if ($Report) { + if ($PSBoundParameters.ContainsKey('Scenario') -or $Unit) { Fail '-Report needs every scenario on every unit in the rig; drop -Scenario and -Unit.' } + $shaping = @('Rate', 'Seconds', 'Crc', 'MaxLossPercent', 'SkipBuild') | Where-Object { $PSBoundParameters.ContainsKey($_) } + if ($shaping) { Fail "-Report runs with the default settings and a fresh build; drop $((@($shaping) | ForEach-Object { "-$_" }) -join ', ')." } + $types = @($units | ForEach-Object { $_.type }) + if (-not ($types -contains 'Shimmer3') -or -not ($types -contains 'Shimmer3R')) { + Fail "-Report needs at least one Shimmer3 and one Shimmer3R in the rig (types found: $($types -join ', '))." + } + $dirty = (git -C $repo status --porcelain) -join "`n" + if ($dirty) { Fail "-Report needs a clean working tree, so the tested code is exactly the commit:`n$dirty" } + $commit = ((git -C $repo rev-parse HEAD) -join '').Trim() + $remote = ((git -C $repo remote get-url origin) -join '').Trim() + $githubRepo = ([regex]::Match($remote, 'github\.com[:/](.+?)(\.git)?$')).Groups[1].Value + if (-not $githubRepo) { Fail "Cannot tell the GitHub repository from origin ($remote)." } + if (-not (Get-Command gh -ErrorAction SilentlyContinue)) { Fail '-Report posts the result with the GitHub CLI (gh); install it and log in.' } + gh api "repos/$githubRepo/commits/$commit" --silent 2>$null + if ($LASTEXITCODE -ne 0) { Fail "Commit $commit is not on GitHub ($githubRepo); push it first." } +} + +# --- Build --------------------------------------------------------------------------------------- +# ShimmerDriverPC's settings.gradle finds ShimmerDriver at ../../Shimmer-Java-Android-API/ShimmerDriver. +if ((Split-Path $repo -Leaf) -ne 'Shimmer-Java-Android-API') { + Fail ("ShimmerDriverPC only builds from a folder named Shimmer-Java-Android-API (its settings.gradle finds its siblings that way), " + + "and this checkout is $repo. Make a junction and run from it:`n" + + " New-Item -ItemType Junction -Path '$(Join-Path (Split-Path $repo -Parent) 'Shimmer-Java-Android-API')' -Target '$repo'") +} +function JavaMajor([string]$javaHome) { + $release = Join-Path $javaHome 'release' + if (-not (Test-Path $release)) { return 0 } + $m = [regex]::Match((Get-Content $release -Raw), 'JAVA_VERSION="(?:1\.)?(\d+)') + if ($m.Success) { return [int]$m.Groups[1].Value } else { return 0 } +} +if (-not $env:JAVA_HOME -or (JavaMajor $env:JAVA_HOME) -lt 11) { + $jdk = @(Get-ChildItem 'C:\Program Files\Amazon Corretto', 'C:\Program Files\Eclipse Adoptium', 'C:\Program Files\Java' -Directory -ErrorAction SilentlyContinue | + Where-Object { (JavaMajor $_.FullName) -ge 11 } | Sort-Object { JavaMajor $_.FullName }) | Select-Object -First 1 + if (-not $jdk) { Fail 'No JDK 11 or newer found; set JAVA_HOME.' } + $env:JAVA_HOME = $jdk.FullName +} + +$outDir = Join-Path $PSScriptRoot ('out\' + (Get-Date -Format 'yyyyMMdd-HHmmss')) +$reportDir = Join-Path $outDir 'reports' +New-Item -ItemType Directory -Force $reportDir | Out-Null +$sha = ((git -C $repo rev-parse --short HEAD) -join '').Trim() +Write-Host "Java HIL: driver source $sha, JDK $(JavaMajor $env:JAVA_HOME) ($env:JAVA_HOME)" +Write-Host "Results: $outDir" + +# --no-watch-fs: Gradle's file watcher can miss edits made through the real path of a junction, +# and would then run stale test classes. +$gradle = Join-Path $gradleRoot 'gradlew.bat' +if (-not $SkipBuild) { + Write-Host 'Building...' + Push-Location $gradleRoot + & $gradle ':testClasses' --no-watch-fs --console=plain *> (Join-Path $outDir 'build.log') + $buildExit = $LASTEXITCODE + Pop-Location + if ($buildExit -ne 0) { Fail "Build failed; see $(Join-Path $outDir 'build.log')" } +} + +# --- Run ----------------------------------------------------------------------------------------- +function Invoke-Scenario([string[]]$gradleArgs, [int]$timeoutSeconds, [string]$logFile) { + $p = Start-Process -FilePath $gradle -ArgumentList $gradleArgs -WorkingDirectory $gradleRoot -NoNewWindow -PassThru ` + -RedirectStandardOutput $logFile -RedirectStandardError "$logFile.err" + if (-not $p.WaitForExit($timeoutSeconds * 1000)) { + # A test JVM stuck in a deadlock outlives the Gradle client; stopping the daemons ends it. + & $gradle --stop *> $null + $p.Kill() + return $true + } + return $false +} + +$results = @() +$runs = 0 +foreach ($u in $units) { + foreach ($s in $Scenario) { + if ($runs++ -gt 0) { Start-Sleep -Seconds $SettleSeconds } + $label = "$($u.name) $s" + Write-Host "Running $label on $($u.comPort)..." -NoNewline + $gradleArgs = @(':hilTest', '--no-watch-fs', '--console=plain', '--tests', "$testClass.$s", + "-Phil.port=$($u.comPort)", "-Phil.mac=$($u.mac)", "-Phil.unit=$($u.name)", "-Phil.type=$($u.type)", + "-Phil.rate=$Rate", "-Phil.seconds=$Seconds", "-Phil.maxLossPercent=$MaxLossPercent", "-Phil.outDir=$reportDir") + if ($Crc) { $gradleArgs += "-Phil.crc=$Crc" } + $safe = "$($u.name)_$s" -replace '[^\w.-]', '_' + $log = Join-Path $outDir "$safe.console.txt" + $timedOut = Invoke-Scenario $gradleArgs $ScenarioTimeoutSeconds $log + + $verdict = 'ERROR' + $detail = '' + $xml = Join-Path $gradleRoot "build\test-results\hilTest\TEST-$testClass.xml" + if ($timedOut) { + $verdict = 'TIMEOUT' + $detail = "did not finish within $ScenarioTimeoutSeconds s; stopped (see $safe.console.txt)" + } + elseif (Test-Path $xml) { + Copy-Item $xml (Join-Path $outDir "$safe.junit.xml") + $case = ([xml](Get-Content $xml -Raw -Encoding UTF8)).testsuite.testcase | Where-Object { $_.name -eq $s } | Select-Object -First 1 + if (-not $case) { $detail = 'the scenario did not run (see the console)' } + elseif ($case.failure) { $verdict = 'FAIL'; $detail = (($case.failure.message -split "`n")[0]) -replace '^java\.lang\.AssertionError: ', '' } + elseif ($case.skipped) { $verdict = 'SKIP'; $detail = 'skipped' } + else { $verdict = 'PASS' } + Remove-Item $xml + } + else { + $detail = ((Get-Content $log, "$log.err" -ErrorAction SilentlyContinue | Select-String 'error|FAILURE|wrong' | Select-Object -First 2) -join ' ').Trim() + } + Write-Host " $verdict" -ForegroundColor $(if ($verdict -eq 'PASS') { 'Green' } elseif ($verdict -eq 'SKIP') { 'Yellow' } else { 'Red' }) + $results += [pscustomobject]@{ Unit = $u.name; Port = $u.comPort; Scenario = $s; Result = $verdict; Detail = $detail } + } +} + +# --- Collect ------------------------------------------------------------------------------------- +# Every run that reached a verdict wrote a report; the gate's status rests on them. +foreach ($r in $results) { + if ($r.Result -ne 'PASS' -and $r.Result -ne 'FAIL') { continue } + $name = ($r.Scenario -creplace '([A-Z])', '_$1').ToLower() + "_$($r.Unit -replace '[^\w.-]', '_').json" + if (-not (Test-Path (Join-Path $reportDir $name))) { + $r.Result = 'ERROR' + $r.Detail = ("no report written ($name). " + $r.Detail).Trim() + } +} +$summary = [pscustomobject]@{ + driver = $sha; rate = $Rate; seconds = $Seconds; crc = $(if ($Crc) { $Crc } else { 'driver default' }) + settleSeconds = $SettleSeconds; results = $results +} +$summary | ConvertTo-Json -Depth 4 | Set-Content (Join-Path $outDir 'summary.json') + +Write-Host '' +$results | Format-Table -AutoSize -Wrap | Out-String -Width 200 | Write-Host +# A skipped scenario did not run, so it is not a pass: the exit code and the gate's status agree. +$failed = @($results | Where-Object { $_.Result -ne 'PASS' }) +$passed = @($results | Where-Object { $_.Result -eq 'PASS' }) + +if ($Report) { + $firmware = @{} + Get-ChildItem $reportDir -Filter '*.json' -ErrorAction SilentlyContinue | ForEach-Object { + $r = Get-Content $_.FullName -Raw | ConvertFrom-Json + if ($r.firmware -and $r.unit) { $firmware[$r.unit] = "$($r.hardware) $($r.firmware)" } + } + $tested = @($units | ForEach-Object { if ($firmware[$_.name]) { $firmware[$_.name] } else { $_.type } }) | Sort-Object -Unique + $state = if ($passed.Count -eq $results.Count) { 'success' } else { 'failure' } + $description = "$($passed.Count)/$($results.Count) passed over Classic: $($tested -join ', ')" + if ($description.Length -gt 140) { $description = $description.Substring(0, 137) + '...' } + gh api -X POST "repos/$githubRepo/statuses/$commit" -f state=$state -f context=java-hil -f description=$description --silent + if ($LASTEXITCODE -ne 0) { + Write-Host 'Could not post the commit status; the release will not see this run.' -ForegroundColor Red + exit 2 + } + Write-Host "Posted 'java-hil' = $state on $githubRepo@$($commit.Substring(0, 8)): $description" +} + +if ($failed.Count -gt 0) { + Write-Host "$($failed.Count) of $($results.Count) did not pass. Reports and console output: $outDir" -ForegroundColor Red + exit 1 +} +Write-Host "All $($results.Count) passed. Reports: $outDir" -ForegroundColor Green +exit 0