We have released RumiCar Simulator v12.0.0. The release notes below are also available on GitHub.
v12.0.0
The learning API RC_read is no longer cut off at a fixed distance by the library: the program now decides how far to trust the readings (the limit) with RC_setReadLimit (Stage BQ; the driving physics and the ranging are untouched — driving with the shipped samples and the result of the shipped official sample race are unchanged. The three shipped language samples and the three Python car-type programs have the same verifyHash as v11.1.0 on all 56 tabletop courses that have a finish. The official sample race’s verifyHash e9f1da0b and the frozen hashes f0–f3 are also the same as before, and only the resultSha256 of the result file was re-pinned because it includes the version (engineVer)). The names and the meaning are the same as in the real-car libraries (Arduino RumiCar-lib v0.7.0, RasPi/RumiCar.py 0.7.0 for the Raspberry Pi, RumiCar-Zero2Cam v0.7.0). Your program may behave differently — a program that uses RC_read and does not call RC_setReadLimit now receives numbers for distances that used to be -3, on the tabletop and at mid-scale. (1) The default of RC_read — v11.x returned -3 for readings beyond 200 mm on the tabletop (400 mm at mid-scale). Since v12.0.0 it returns readings up to the sensor range (2,000 mm on the tabletop, 4,000 mm at mid-scale) as they are. -3 is returned beyond the sensor range, when nothing reflects, on low signal, and above the limit set by the program. Full scale never had a cut-off and is unchanged (only with sensor noise ON, a reading that noise pushes slightly beyond the sensor range is now -3 too, the same order of checks as in the real-car libraries). To receive the same values as in v11.x, add RC_setReadLimit(200) on the line after RC_setup() in setup() (tabletop; 400 for the same values as v11.x at mid-scale). (2) RC_setReadLimit(limit) / RC_setReadLimit(direc, limit) — sets the limit [mm] up to which RC_read readings are trusted (call it once in setup()). One argument sets front, left, right and rear; two arguments set that direction only (LEFT / CENTER / RIGHT / REAR). The limit is 1 to the sensor range (2000 on the tabletop, as on the real car), 0 means no limit (the default), values outside the range are clamped to 0 to the sensor range, and fractions are truncated toward 0. Readings above the limit are returned by RC_read as -3 (a reading exactly at the limit stays a distance; -1 and -2 are unchanged). It returns 1, or 0 for a bad direction, in which case nothing is changed. A value that is not a number (a non-numeric string, None, a list) counts as no limit, with one warning per value. REAR can be set without a rear sensor; RC_read(REAR) still returns -1. RC_setup does not change the limit. The limit goes back to none each time a run (▶ or 🏁) starts. It takes 1 or 2 arguments: a call with another number is a runtime error with a line number in C++ and Python (JavaScript treats a call with no argument as no limit with a warning, and ignores a third argument). The raw read sensorN.readRangeSingleMillimeters() (C++, JavaScript) and the distances shown on screen are not affected by the limit. The limit is the millimetre value written in the program and does not scale with the regime. (3) Replacing -3 — replacing -3 with 999 before comparing left and right (if d == -3: d = 999) steers the wrong way when no limit is set, because distances of 1000 mm and more then count as “closer than -3”. Replace it with a value larger than any distance RC_read returns (e.g. 9999 on the tabletop), or set a limit with RC_setReadLimit. (4) Shipped samples and explanations — the samples (Wall Hugger in C++ / Python / JavaScript) and the three Python car-type programs (Wall Hugger / 4WD / FF) call RC_setReadLimit(200) in setup(), and their replacement for -3 changed from 999 to 9999 (they drive as in v11.1.0 on the tabletop). The nine full-scale competition programs (Circuit Racer, Range-Flow Estimator, Recon Racer and others) use RC_read without setting a limit (full scale never had a cut-off, so they drive the same at full scale). The explanations (Help, Specs & Limits, Physics Model, the system guide, the car-type program notes) refer to the limit by name, as “the limit set with RC_setReadLimit“. The recommended example, its basis and how to choose the value are written in one place only: “Choosing the limit” in §12 of the physics model document docs/physics_model.en.md. To change the limit, change one line of the program and that subsection. (5) Why — the laser of a real ToF spreads out in a cone and, depending on where the sensor is mounted, picks up the floor beyond some distance. That distance depends on the body, the mounting position and the floor, so the library no longer decides it and the program does (the same decision as in the real-car libraries v0.7.0). The simulator’s ranging has no floor reflection, so a program with a wider limit that drives in the simulator is not guaranteed to drive the same way on the real car. (6) Verification — a table made by running the reference RasPi/RumiCar.py 0.7.0 (105 sequences of RC_setReadLimit calls — for the C++ processor, the 83 that can be written in C++ — × 15 raw values × 3 directions) matches the return values, the number of warnings and the RC_read values after the calls, for the host functions and through the C++, Python and JavaScript processors (chapter G of the verification gate wf_bo1_steer; walls are placed and measured by the production ranging). Exercise-3.3 and 4.2-Answer of RumiCar-lib v0.7.0, Exercise-3.1 to 3.3 of RasPi and the sample drive.py of Zero2Cam v0.7.0 run through the processors unmodified (drive.py has no params.json here, so it stops at p["stop_mm"] in loop() as before). Chapter D of wf_bh6_docs checks that the samples’ verifyHash equals v11.1.0 and that no limit value remains in the explanations. The permanent gates stay at 82, and browser/check_bq1_readlimit.mjs was added to the real-browser checks. Unchanged: the driving physics, the ranging itself (sensor range, cone drawing, noise/optics models), the raw-read values, RC_read at full scale (except the sensor-noise case in (1)), the values and warnings of RC_steer / RC_drive, the deterministic engine of official races (🏁), the saved-data format and the tabletop courses. Records of official races confirmed in v11.x or earlier are treated as records of another version, as before (a program that uses RC_read without setting a limit can give a different result when re-run in v12.0.0).
Verifying this release yourself
git clone https://github.com/RumiCar-group/RumiCar-Simulator.git
cd RumiCar-Simulator
node wf_run_all.mjs # the full assertion-gate suiteThe suite runs from a fresh clone with no dependencies beyond Node.js.
The real-browser checks under browser/ additionally need npm install and a display.
