The First IoT JSR: Units of Measurement - DevoXX BE 2015

@UnitAPI#JSR363DevoxxBE

The First IoT JSR: Units of Measurement

JSR-363Werner Keil | Otávio Santana | Mohamed Taman@wernerkeil | @otaviojava | @_tamanm @UnitAPIhttps://www.jcp.org/en/jsr/detail?id=363http://unitsofmeasurement.github.io


The First IoT JSR: Units of MeasurementWerner Keil

•Consultant – Coach•Creative Cosmopolitan•Open Source Evangelist•Software Architect•Spec Lead – JSR363•JCP EC Member

[www.linkedin.com/in/catmedia]

Twitter @wernerkeil | Email [email protected]


What is JSR-363?

5,999 milesA Quantity

A UnitBrussels

São Paulo


Why do we need JSR-363?There are no specifications or standards for handling units in Java.

The current solution is to use primitives, that don’t provide any Type Safety.

The errors are difficult to find using unit testing: Interface and Internationalization (e.g. radian/degree,

meters/feet);Arithmetic operations (e.g. overflow);Conversion between units (e.g. from same domain);



A Unit

What is the problem, in code?

int distance = 5999; //in milesfloat speed = airplane.getSpeed(); //in km/hSystem.out.println(“TTD: “ + (distance/speed) + “ h”);


What is JSR-363?A framework supporting robust representation and correct handling of quantities.

JSR 363 establishes safe and useful methods for modeling physical quantities.


What is JSR-363?Interfaces and abstract classes supporting unit operations including:

Checking of unit compatibility;Expression of measurement in various units; andArithmetic operations on units.

Concrete classes implementing standard unit types (base, derived), unit conversion and representation.

@YourTwitterHandle#DVXFR14{session hashtag} @UnitAPI#JSR363DevoxxBE

CORE THEORY AND CONCEPTSSome Basic Science behind the API


What is a Unit?c. (a) Any determinate quantity, dimension, or magnitude adopted as

a basis or standard of measurement for other quantities of the same kind and in terms of which their magnitude is calculated or

expressed.Oxford English Dictionary

Or … A well defined standard we all know?Unit DefinitionSecond The duration of 9,192,631,770 periods of the radiation corresponding to the

transition between the two hyperfine levels of the ground state of caesium 133 atom

Kilogram The mass of the international prototype kilogram [a very special lump of metal]

Metre The distance travelled by light in a vacuum in 3.3356409519815204957557671447492e-9 seconds


A Standard Measurement …“The nice thing about standards is that you have so many to choose

from.”Andrew S. Tanenbaum,

Computer Networks 2nd ed., p. 254

Foot

Mile Yard Chain

FathomFurlongInchNautical Mile

Statute Mile

astronomical unit (AU)

Light yearParsec(or meter)

Passus (roman)

Hand

ångström

Scots/Welsh/English Mile

Metre fermi micron

Thou (or mil)League

rod/perch/pole

nail

Barleycorn

link

ell Cubitfinger

palm

Poppyseed

Milli Centi Kilo


System of UnitsSystem International d’Unites (SI)

The accepted basis for most scientific and engineering activities.

Standard units for key physical quantities (length, time, power etc.)

Standard prefixes (kilo/micro etc.)

Standard dimensions…

Système

International d'Unités


DimensionAllows analysis of a quantity by the rational powers of the 7

fundamental dimensions (quantities are compatible when they have the same dimensions):

length (L), mass (M), time (T), electric charge (I), absolute temperature (Θ), amount of substance (N) and luminous intensity (J)

Examples:Speed = length/time - it’s dimensions are L=1,T=-1 (rest 0) (e.g. metre/second - ms-

1)

Acceleration is speed/time (m/s/s or ms-2) L=1, T=-2

Force is mass x acceleration M x ((length/time)/time) or M=1, L=1, T=-2

Molar Entropy: M=1 L=2 T=−2 Θ=−1 N=−1 (trust me!)


QuantityA physical attribute of a thing. Something that can be measured and

has units. Compatible quantities have the same dimension…

Examples:• Time• Length• Speed• Amount of Substance• Luminous Intensity• Volume• Mass• Force• Power• Electrical Current

• Magnetic Flux Density• Volumetric Flow Rate

• Fuel Economy*• Percentage

• Eggs per carton• Sheep per hour• Bits and bytes …

… ∞


Unit ConversionThe process of conversion depends on the specific situation and the

intended purpose. This may be governed by regulation, contract, technical specifications or other published standards.

Wikipedia


LEARNING FROM THE PAST…Some examples of how things can go wrong…


Some real-life mishaps…NASA “Star Wars” Initiative, 1983

Sea Level

http://upload.wikimedia.org/wikipedia/commons/9/97/Sts-51-g-patch.png


Some real-life mishaps…[Cost $125M]

“Preliminary findings indicate that one team used US/English units (e.g. inches, feet and pounds) while the other used metric units for a key spacecraft operation.”

NASA Mars Climate Orbiter, 1999


1983: The Gimli “Glider”

Photo: Wayne Glowacki

Maintenance workers performed a test that estimated that 7,682 litres of fuel were in the tank. They knew they needed 22,300 kilograms of fuel for the remaining flight, so the question was, How much fuel, in litres, should be pumped from the fuel truck into the aircraft? They were forced to resort to a manual calculation:

They multiplied 7,682 L by 1.77, the density of the fuel provided by the refuelling company on their documentation: The aircraft, according to their calculations, currently had 13,597 kg of fuel.

Subtracting from 22,300 kg, they decided they needed to add 8,703 kg of fuel.

Dividing by 1.77 — the same density used in the previous calculation — yields 4,916 L, which was pumped into the aircraft.

However, 1.77 was the density of the fuel in pounds per litre (lb/L), not kilograms per litre (kg/L); the correct figure for kg/L would have been 0.80. As a result, they ended up with less than half of the required amount of fuel on board. (The fuel's density depends on characteristics of the fuel, so it's not a constant, and the value must be taken from documentation accompanying the fuel.)


2001: Escape of the 250kg tortoise

Los Angeles Zoo lent Clarence, a 250-kilogram, 75-year-old Galapagos tortoise, to the Exotic Animal Training and Management Program at Moorpark College in Moorpark CA.

The first night in his new home, Clarence wrecked it: “He just pushed one of the fence poles right over,” said Moorpark's Chuck Brinkman.

The L.A. Zoo warned that Clarence was big, and needed an enclosure for an animal that “weighs in at about 250”, so that's what the college built.

Unfortunately, they thought the zoo meant 250 pounds, so the enclosure wasn't adequate for holding a 250-kilogram (552 lbs) beast.

Clarence


Conversion problemsThese are examples of confusion on the units in application.

But there is also ambiguity on the unit itself:10 Gallons … Gallon Dry / Gallon Liquid - Gallon US / Gallon UK28 Days … Day Sidereal / Day Calendar38 Degrees … Degree Celsius / Degree Fahrenheit / Degree

Angle

And the wrong conversion factors:static final double PIXEL_TO_INCH = 1 / 72;double pixels = inches * PIXEL_TO_INCH;


THE C

ODE


What is the problem, in code?

int distance = 5999; //in milesfloat speed = airplane.getSpeed(); //in km/hSystem.out.println(“TTD: “ + (distance/speed) + “ h”);


A Unit


What is JSR-363, in code?

Quantity<Length> distance = Quantities.getQuantity(5999, US.MILE);Quantity<Speed> airplaneSpeed = getAirplaneSpeed();Quantity<Time> timeToDest = (Quantity<Time>)distance.divide(airplaneSpeed);System.out.println(“TTD: “ + timeToDest.to(Units.HOUR));

TTD: 10.216345960256564 h


Who is going to use JSR-363?Java developers who work with physical quantities need to handle measurements in their programs.

Inadequate models of physical measurements can lead to significant programmatic errors.

Platform providers and developers can provide and use a more well-defined API.

Embedded developers can have less error-prone, more self-documented code.


JSR-363: Internal StructureJSR-363 is broken down into the following packages:

Package Descriptionjavax.measure Core API interfaces (e.g. Dimension, Quantity, Unit)javax.measure.format [optional] Interfaces for quantity/unit formatting and parsingjavax.measure.quantity

[optional] Interfaces for quantity types (e.g. Mass, Length)

javax.measure.spi [optional] Service Provider Interface (implementation discovery)

Reason: We target very small devices running Java ME (CLDC 8) for IoT applications (e.g. sensors, wearables, gateways etc.)


JSR-363: Systems and ExtensionsOn top of JSR-363 we offer support

for various unit systems:• Reusable Quantities• SI System• Common Systems (US, Imperial)• ISO 80000• UCUM

Reason: By providing small, modularlibraries, we live and sometimes forestallthe ideas behind Java ME 8 or Jigsaw andoffer great flexibility to IoT solutions


DIAMONDS ARE FOREVERISO / IEC 80000

Images: Eon Production


Demo


Demo 1: Strongly type your codeV2COM created an embedded power measurement system that tracks

how much individual circuits are using in an industrial application.

We want to:1. Avoid unit ambiguity2. Avoid quantity ambiguity that

lead to calculation errors


Demo 2: Intel EdisonAnticipating Intel’s JavaOne 2015 announcement of full Java support

on IoT devices like Intel Edison, I made Java SE 8 and JSR 363 work on Intel Edison in March 2015.

We want to:1. Avoid unit ambiguity when

receivingdata from sensors or propagating it to Cloud solutions like Intel IoT Analytics

2. Format a measurement without loss of data


Action

!

Images: Columbia Pictures / Eon Production


How can YOU make JSR-363 work?It’s still an active JSR: YOU can get involved.

We are participating in the Adopt-a-JSR program - 3 JUGs have so far joined the EG! (Morocco JUG, SouJava, JUG Chennai).

You can download the code, file JIRA / GitHub Issues for bugs or needs and follow the discussion in our mailing lists.

We’re always looking for new ideas and use cases.


And

the O

scar

go

es

to…


JSR-363 timelineMarch 11, 2014: SubmittedApril 7, 2014: Creation approvedDec 2014 – January 2015: Early Draft (done)Q3/2015 – Q4/2015: Public Review (tied with DevoXX)Q2/2016 : Final DraftQ3/2016: Final Release


Links to JSR-363Public mailing list(s) and/or forum(s)

Units-Dev on Google GroupsUnits-Users on Google GroupsEG only mailing list on java.net, archive fully visible

The JSR page on JCP.org…And two other “JSR project websites”:

Main project website is on GitHub (unitsofmeasurement)Java.net site is used for downloads or JIRA.

And you can get sample code at our GitHub.

https://groups.google.com/forum/#!forum/units-dev

https://groups.google.com/forum/#!forum/units-users

https://java.net/projects/unitsofmeasurement/lists/experts/archive

https://jcp.org/en/jsr/detail?id=363

http://unitsofmeasurement.github.io/

http://unitsofmeasurement.java.net/

https://github.com/unitsofmeasurement/uom-demos


Building JSR-363 for Java SEYou need Java SE 8 SDK + IDE (Like Eclipse)git clone https://github.com/unitsofmeasurement/unit-api.gitgit clone https://github.com/unitsofmeasurement/unit-ri.git

orgit clone https://github.com/unitsofmeasurement/uom-se.git

Use Maven to compile & install mvn install and you’re done.

http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

http://www.eclipse.org/downloads/packages/eclipse-ide-java-developers/lunasr2


Building JSR-363 for Java MEYou need Windows, Java SE 8 SDK, Eclipse or Netbeans, Java ME 8 SDK + Java ME 8 SDK Plugins (Netbeans or Eclipse)

git clone https://github.com/unitsofmeasurement/unit-api.gitgit clone https://github.com/unitsofmeasurement/unit-ri.git

Create new Java ME 8 Project for APICreate new Java ME 8 Project for RICreate new Java ME 8 Project for your AppOrgit clone https://github.com/unitsofmeasurement/uom-demos.git> javame/medemo (see instructions in README.md)

http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

http://www.oracle.com/technetwork/java/embedded/javame/javame-sdk/downloads/javamesdkdownloads-2166598.html

https://github.com/unitsofmeasurement/unit-api.git

https://github.com/unitsofmeasurement/unit-ri.git

https://github.com/unitsofmeasurement/uom-demos.git

https://github.com/unitsofmeasurement/uom-demos.git


Q & A


Than

ks!

The First IoT JSR: Units of Measurement - DevoXX BE 2015

Technology