Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 51 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# 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.
Expand Down Expand Up @@ -46,6 +49,10 @@ on:
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'
Expand All @@ -62,12 +69,14 @@ jobs:
# 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'
Expand Down Expand Up @@ -121,6 +130,35 @@ jobs:
} >> "$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:
Expand Down Expand Up @@ -272,6 +310,7 @@ jobs:
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:
Expand All @@ -286,16 +325,27 @@ jobs:
- 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" \
--generate-notes ${PREVIOUS_TAG:+--notes-start-tag "$PREVIOUS_TAG"} \
--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"

Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
22 changes: 22 additions & 0 deletions ShimmerDriverPC/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,26 @@ repositories {
test {
// this test requires a physical Shimmer2r to run
exclude '**/API_00001_ShimmerPC_GeneralBluetoothShimmer2R.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.<name>=<value> reaches the tests
// as the system property hil.<name>.
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 {
Expand Down Expand Up @@ -103,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
Expand Down
161 changes: 161 additions & 0 deletions ShimmerDriverPC/src/test/java/com/shimmerresearch/hil/HilReport.java
Original file line number Diff line number Diff line change
@@ -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<String> failures = new ArrayList<>();
private List<StreamAnalysis.Sample> samples;

HilReport(String scenario, String unit, String port, String mac, String type, Map<String, String> 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<StreamAnalysis.Sample> 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<String> failures() {
return failures;
}

/** Writes <scenario>_<unit>.json, .csv (samples, if any) and .driver.log into outDir. */
void write(File outDir, List<String> events, List<String> 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);
}
}
}
Loading
Loading