Apps for Homey

These calculations rest on suncalc, a third-party library whose actual behaviour had to be checked step by step, its documentation still describing an earlier version. Three gaps between what it documents and what it returns had to be found and corrected before the app said anything true.

1. 01

   From apparent height to geometric height

   hauteur géométrique = hauteur apparente − réfraction(max(hauteur géométrique, 0))

   suncalc returns an apparent height, atmospheric refraction included, while sunrise, sunset and the twilights are defined on the geometric height, that of the disc's true centre. But its refraction formula first clamps the height to zero, which adds a constant 0.484° everywhere below the horizon, at −18° as much as at −1°. Exposing the apparent height would have made a “below −6°” threshold fire two minutes after civil dawn, for the same definition. Below the horizon, removing the refraction is thus a plain subtraction; above it, where it varies with height, it takes iteration, and a single pass crossing the kink oscillates without converging: six are needed.

2. 02

   Which way the sun is moving, even with no sunrise or sunset

   montant = maintenant < midi solaire

   A height of −3° is a dawn in the morning, a dusk in the evening: the sky's phase therefore depends on which way the sun is moving, not on its height alone. That direction cannot be read off sunrise, which does not exist in every season or at every latitude, but off solar noon, the only reference that stays defined even on a day of midnight sun or polar night.

3. 03

   Three ways of saying nothing

   événement absent = null, undefined, ou Invalid Date selon le champ

   An event that does not happen that day, an astronomical dusk in the middle of a Nordic summer, say, does not always take the same absent shape: depending on the field, suncalc returns `null`, `undefined`, or an invalid date. A plain `instanceof Date` does not catch all three, and reading the time of an invalid date throws rather than signals it. All three shapes are therefore reduced to one single signal before reaching the rest of the code.

4. 04

   The ladder of sky phases

   jour ≥ 6° > heure dorée ≥ −0,833° > crépuscule civil ≥ −6° > nautique ≥ −12° > astronomique ≥ −18° > nuit

   Ten phases follow one another between full daylight and full night, each bounded by a geometric height of the sun: daylight above 6°, golden hour down to the official sunrise at −0.833°, then the three twilights, civil, nautical and astronomical, at −6°, −12° and −18°, before night. The same ladder, read the other way, gives the morning phases. This is the ladder the tile's own capability reads, its ten labels coming from the manifest rather than being duplicated in the translations.

5. 05

   The moon's phase and age

   phase lunaire ∈ [0, 1[, 0 = nouvelle lune, 0,5 = pleine lune ; âge = phase × 29,530588853 j

   suncalc returns the lunar phase as a fraction of the cycle between 0 and 1, where 0 is new moon and 0.5 is full moon. That single fraction is turned into one of the eight usual names, new moon, waxing crescent, first quarter…, by a plain series of boundaries. Multiplied by the mean length of a lunation, 29.530588853 days, it also gives the moon's age, with no separate calculation: the same fraction carries both pieces of information.

6. 06

   Easter Sunday, and its cross-check

   algorithme grégorien anonyme (Meeus, Jones, Butcher), confronté à l'algorithme de Gauss de 1900 à 2200

   The eleven public holidays of the general regime all follow from a fixed date or from Easter Sunday, computed offline by the anonymous Gregorian algorithm, valid for any year of the Gregorian calendar. Rather than taking it on trust, a test checks it against Gauss's algorithm, formulated independently, across the three hundred and one years from 1900 to 2200: the two agree every single year. Alsace-Moselle adds two days to the general regime, Good Friday and 26 December, under local law.

7. 07

   The right instant, in the right time zone

   instant local = mur UTC − décalage(fuseau), décalage recalculé deux fois après un premier essai

   Scheduling an announcement for six in the evening local time requires knowing that zone's offset at that very instant, yet the offset itself depends on the instant still being sought, because of daylight saving. The first guess starts from a wall-clock hour treated as UTC, then the real offset is recomputed at that corrected instant, twice in a row: the process converges even on a clock-change day, and a test checks it over three hundred and sixty-five days and three time zones.

A trend is easy to announce and hard to stand behind: two readings are enough to draw a line, and a noisy sensor draws a new one every time. Here is what the app does so that it says “it is rising” only when it really is.

1. 01

   The line, by Theil-Sen

   pente = médiane des (vⱼ − vᵢ) ⁄ (tⱼ − tᵢ), pour toutes les paires i < j

   The slope is not fitted by least squares but taken as the median of the slopes of every pair of points. An outlier only enters the pairs that contain it, a minority, and the median discards it. Least squares, by contrast, minimises squared deviations: one wild point then outweighs all the others together. Over three hundred points that is 44,850 pairs, a few milliseconds.

2. 02

   The sensor's noise

   σ = 1,4826 × médiane( |rᵢ − médiane(r)| ), avec rᵢ = vᵢ − (a + b·tᵢ)

   Noise is measured on the deviations from the line, not on the raw values: a clear rise is not noise. The median absolute deviation is used, which the factor 1.4826 turns into a standard deviation. A floor guards against a trap: on a quantised sensor, an anemometer reading whole kilometres per hour for instance, more than half the deviations can be identical and the estimate fall to zero. Noise is therefore never claimed finer than half the sensor's own step.

3. 03

   The uncertainty on the slope

   σ_pente = σ ⁄ ( √n × σ_t ) × 3600

   The noise of a reading is not the noise of the slope. The more points there are, the surer the slope, hence the square root of n; and the more they are spread over time, the surer still, hence the standard deviation of the timestamps in the denominator. Ten readings taken within a minute say far less about a trend than the same ten spread over an hour.

4. 04

   The deadband

   zone morte = k × σ_pente, avec k = 3 par défaut

   Below three times its own uncertainty, a slope cannot be told apart from noise: the app reports “steady” rather than inventing a movement. The factor is adjustable, and it can be replaced by a fixed threshold in units per hour when you know what you are looking for.

5. 05

   The confidence

   fiabilité = min( 100 ; 50 × |pente| ⁄ (k × σ_pente) )

   It says by how much the slope exceeds its own noise, and nothing else. Fifty means the slope is exactly the deadband, one hundred that it is twice it. A clear slope on a noisy sensor can therefore be highly reliable, and a tiny slope on a precise sensor not reliable at all.

6. 06

   The forecast and the time to threshold

   v̂ = a + b·t_dernier · prévision = v̂ + b × horizon · échéance = (seuil − v̂) ⁄ b

   Both start from the model's value at the last instant, never from the last raw reading: extrapolating from a noisy point would carry that noise forward. The time to a threshold returns nothing in the three cases where a number would lie, namely a slope inside the deadband, a threshold already crossed or on the wrong side, and a time beyond twenty-four hours, a distance at which the slope will have changed several times.

7. 07

   The hysteresis

   changement retenu si confirmé 2 fois de suite ET direction précédente tenue ≥ 300 s

   This is the only thing that stops a shutter from flapping around its threshold. A change of direction is accepted only after two consecutive confirmations, and only if the previous direction held for at least five minutes. Both conditions are required together.

8. 08

   The turning point

   fenêtre coupée en deux, chaque moitié ajustée ; signes opposés et hors zone morte → pic ou creux

   A single line cannot see a peak: it averages it away. The window is therefore cut in two halves, each fitted separately, each needing at least four points. If both slopes clear the deadband and have opposite signs, the app reports a peak when the first was rising, a trough when it was falling.

Predicting a pass means knowing where the station will be, where that puts it relative to you, and whether you will be able to see it. The three questions are handled separately, and the third is the one where mistakes are easiest.

1. 01

   Where the station will be

   le service répond aux instants futurs, jusqu'à 24 h, balayage au pas de 60 s, 30 instants par requête

   There is no orbit propagator on board, and that is deliberate. The service accepts a request for the position at a future instant, up to twenty-four hours ahead, so the window can simply be scanned minute by minute. A whole day costs forty-nine requests, against a stated quota of three hundred and fifty per five minutes. The scan runs only at startup, at midnight, and on demand.

2. 02

   The angle between you and the point below it

   γ = 2·arcsin( √( sin²(Δφ⁄2) + cos φ₁ · cos φ₂ · sin²(Δλ⁄2) ) )

   This is the angle at the Earth's centre between your home and the point directly under the station. It uses the haversine formula rather than the direct cosine, which loses all precision when two points are close, which is exactly when the station passes overhead. A test exercises it on two points a metre apart.

3. 03

   The elevation above the horizon

   h = arctan2( cos γ − R ⁄ (R + a) , sin γ )

   This is what the eye sees, and so the quantity that decides everything. The two-argument arctangent is used rather than a division, which would give infinity at the zenith, where the sine vanishes. The device setting acts on this height, ten degrees by default: below that, a pass is swallowed by roofs and trees.

4. 04

   The two distances, which are not comparable

   d = √( R² + (R + a)² − 2 · R · (R + a) · cos γ )

   The distance to the station is the chord through space, given by the law of cosines. The ground distance is the arc travelled over the surface, R times the angle. When the station is far, the arc is longer than the chord, which is surprising on the tile but perfectly correct: at a hundred degrees apart there are nearly eleven thousand kilometres of ground for ten thousand as the crow flies.

5. 05

   The check that validates the whole geometry

   rayon de visibilité = R · arccos( R ⁄ (R + a) ) ≈ 2 257 km à 420 km d'altitude

   This is the radius of the circle from which the station stands above the horizon. The service publishes a footprint of its own, the diameter of that very circle, so the two can be compared. The measured gap is 1.34 kilometres out of 2,258, six hundredths of one per cent, which matches the choice of Earth radius, mean here and equatorial there. The geometry is thus validated without having to take the service at its word.

6. 06

   Whether the station is lit, and the trap to avoid

   la station est éclairée si γ(station, point subsolaire) < 90° + arccos( R ⁄ (R + a) )

   The service publishes a field called “visibility”, and trusting it would be a mistake. It describes the ground under the station, not the station: it answers “daylight” when it is day below, even though the station is in full sunlight and perfectly visible to a distant observer in the dark. Relying on it led to the conclusion that no pass was visible over twenty-four hours; computing the illumination from the subsolar point, which the service also supplies, brought out two passes, both in the small hours, which is indeed when the station is seen at this time of year. The Earth's shadow is treated as a cylinder, and the altitude adds some twenty degrees to the half-angle.

7. 07

   How dark your sky is

   hauteur du Soleil chez l'observateur < −6°, le crépuscule civil

   This is the condition the service does not provide and which has to be computed here: a lit station crossing a daylit sky stays invisible. The Sun's elevation comes from the NOAA equations, the same as in the Ephemerides app, and the two implementations were compared: they agree to a ten-thousandth of a degree on a value read in operation.

8. 08

   Cutting the series into passes

   un passage = les instants consécutifs où h > 0 ; retenu si son sommet atteint la hauteur minimale

   The scanned series is cut into runs of consecutive instants where the station stands above the horizon. Each run gives a pass, of which the start, the end, the peak and its azimuth are kept. Those whose peak falls short of the configured height are discarded, and a pass is declared visible only if one of its instants meets all three conditions at once. The distance card, for its part, fires only on a downward crossing: otherwise it would fire again at every reading for as long as the station stayed inside the radius.

Vigicrues offers neither a search by coordinates nor by name: the national feed gives every section at once, leaving it to the app to sort them. The Météo des forêts, for its part, only publishes a feed that grows every day, with a département's latest value buried inside it.

1. 01

   The nearest section

   distance ≈ haversine(centroïde du tronçon, position de la Homey)

   Each section is a line, sometimes tens of kilometres long: its position is reduced to the average of every point in its geometry, a centroid, good enough to sort more than three hundred sections by proximity without computing a true distance to the nearest segment. The same list serves pairing, to suggest sections near the Homey, and the search by name.

2. 02

   One reading for every section followed

   un relevé national partagé par tous les appareils, plutôt qu'un par appareil

   The national feed weighs about two megabytes, whatever the number of sections being looked up in it. Fetching it once per followed device would have multiplied that weight for no reason: it is therefore cached for the length of a cycle and shared across every device of the driver, each of which only picks out its own section.

3. 03

   The seasonal gap, told apart from a failure

   hors juin-septembre : le fichier de l'année est absent, pas en panne

   The Météo des forêts is only published during the fire season, from June to September: outside that window, the year's file simply does not exist yet, or any more. The device says so plainly, without mistaking it for a network failure, which is still flagged as such.