Experiment record

Long-term home environmental sensing with SwitchBot, Google Apps Script, and external weather observations (revised)

Twelve SwitchBot environmental sensor endpoints were collected through Google Apps Script at a nominal five-minute cadence. A private dataset containing 104,578 measurement rows was used to analyse thermal behaviour, moisture, CO₂, and agreement with external weather observations. Operational failure of the initial Open-Meteo path and the migration to other public observations are also documented.

Conclusion

A long-term home environmental data logger was implemented using SwitchBot sensors, SwitchBot OpenAPI v1.1, Google Apps Script, and Google Sheets.

The final system handled twelve enabled environmental sensor endpoints at a nominal five-minute cadence. It stored temperature, relative humidity, calculated absolute humidity, CO₂ where available, battery state, API response state, device metadata, and execution diagnostics.

The private dataset analysed here covered approximately 2026-07-28 05:28 to 2026-08-13 21:28 and contained 104,578 measurement rows. The collector recorded 104,564 SUCCESS states and 14 ERROR states.

Even this short summer observation window revealed clear differences among building zones:

• the attic reached 44.3 °C;
• the crawl space stayed within a narrow 23.9–26.2 °C range;
• crawl-space mean relative humidity was about 86.9 %RH, but mean absolute humidity was about 19.86 g/m³, close to the outdoor mean of about 20.08 g/m³;
• living-room CO₂ had a median of about 729 ppm, a 95th percentile of about 906 ppm, and a maximum observed value of 2,037 ppm;
• the household outdoor sensor had temperature correlations of approximately r = 0.924 and r = 0.944 with two independent external observation sources.

The most important moisture-analysis finding was that relative humidity alone can be misleading. High crawl-space %RH did not correspond to a similarly large excess of water vapour. The lower crawl-space temperature substantially increased relative humidity while absolute humidity remained close to outdoor conditions.

The most important operational finding was that an API being technically usable does not guarantee that it is suitable for unattended long-term logging. Open-Meteo worked technically, but access-limit-related missing acquisitions made it insufficiently continuous as the primary external-weather reference for this workflow.

Public-data boundary

This article publishes the experiment and its analysis, not the raw household telemetry.

The following are deliberately withheld:

• SwitchBot Token and Secret;
• device IDs;
• spreadsheet and account identifiers;
• personal room names;
• exact external research institution, station name, and location;
• the exact JMA observation point;
• the raw five-minute household time series;
• installation details that could make the residence easier to identify.

The public record preserves measurement cadence, analysis period, aggregation method, summary statistics, implementation architecture, and operational lessons needed for technical reuse.

1. Objective

The goal was to move beyond checking current temperature and humidity values in a vendor application and instead preserve measurements as a time series that could support later building-environment analysis.

The intended system needed to answer questions such as:

1. How differently do outdoor air, conditioned living space, the crawl space, and the attic respond to weather?
2. Is high relative humidity caused by excess water vapour, low temperature, or both?
3. Can CO₂ provide information related to ventilation and occupancy?
4. How well does a household outdoor sensor track independent regional weather observations?
5. Can the environmental dataset later be integrated with HVAC, hot-water, and appliance electricity data?

2. System architecture

The confirmed acquisition path was:

SwitchBot environmental sensors
        ↓
SwitchBot Cloud
        ↓
SwitchBot OpenAPI v1.1
        ↓
Google Apps Script
        ↓
Google Sheets

External weather observations were later integrated into the workbook for time-based comparison with household environmental measurements.

2.1 Google Sheets structure

Separating measurements, configuration, and logs made failures easier to diagnose during long-term unattended operation.

3. SwitchBot data-acquisition implementation

3.1 OpenAPI authentication

The implementation used SwitchBot OpenAPI v1.1.

For each API request, the collector created an HMAC-SHA256 signature using the Token, current timestamp, nonce, and Secret. The resulting signature was Base64-encoded and sent in the request headers.

The important request headers were:

Authorization: <SwitchBot Token>
sign: <HMAC-SHA256 signature>
t: <Unix time in milliseconds>
nonce: <UUID>

The Token and Secret were not embedded in the script source or spreadsheet. They were stored in Apps Script Script Properties.

3.2 Environmental-sensor discovery

The collector first queried /devices and filtered the returned inventory to environmental sensors.

Observed environmental device types included:

• Meter
• MeterPlus
• MeterPro(CO2)
• WoIOSensor

An early implementation detected only nine environmental candidates. After the device-type filtering was revised, twelve sensor endpoints were recognised.

The implementation lesson is important: environmental-device filtering should be validated against the actual /devices response rather than relying only on an assumed product list.

3.3 Five-minute collection cycle

The main entry point was collectMeasurements(), invoked by an Apps Script time-driven trigger at a nominal five-minute interval.

A collection cycle approximately performed the following steps:

1. refresh the device list when required;
2. load enabled devices from Devices;
3. request /devices/{deviceId}/status for each endpoint;
4. normalize field names across device types;
5. calculate absolute humidity;
6. append one row per device to Measurements;
7. record warnings/errors in Logs;
8. update the last successful acquisition time.

3.4 Duplicate-execution protection

Because the script runs repeatedly, a slow cycle could overlap with the next trigger.

LockService was therefore used to prevent concurrent executions. A new run did not compete with a currently executing run.

3.5 Per-device exception handling

A failure for one endpoint did not terminate the whole collection cycle.

The failed endpoint was logged as an error while collection continued for the other sensors.

This is important for unattended logging because one temporary device/API problem should not create a whole-house data gap.

3.6 Device-list caching

The device inventory did not need to be fetched every five minutes.

The /devices result was cached for approximately 24 hours, reducing unnecessary API traffic.

4. Absolute-humidity calculation

Relative humidity depends strongly on temperature, so the collector calculated absolute humidity and stored it with the raw temperature and relative-humidity measurements.

The implementation used the saturation vapour pressure approximation:

e_s = 6.112 × exp((17.67 × T) / (T + 243.5))

and then calculated absolute humidity:

AH = (2.1674 × e_s × RH) / (273.15 + T)

where:

• T is temperature [°C];
• RH is relative humidity [%];
• AH is absolute humidity [g/m³].

A check using 20 °C and 50 %RH produced approximately 8.64 g/m³.

This derived field later became essential for interpreting the crawl-space moisture conditions.

5. CO₂ collection

For the CO₂-capable sensor, the logger stored CO₂ together with temperature, relative humidity, battery state, and other measurement metadata.

This allowed the same time-series framework to support both thermal/moisture analysis and ventilation-related analysis.

6. External-weather integration

6.1 Initial Open-Meteo implementation

The first external-weather path used Open-Meteo.

Hourly weather observations were downloaded and stored using observation time as the deduplication key.

6.2 Access-limit problem

During unattended operation, the Open-Meteo path encountered API/daily access-limit-related failures.

To reduce request volume, the collection interval was reduced, eventually using approximately one API call every six hours while retrieving multiple hourly observations per call.

The lower request frequency reduced API traffic but did not provide sufficient continuity for this workflow.

6.3 Removing Open-Meteo as the primary source

The SwitchBot environmental series was dense and generally continuous at approximately five-minute resolution.

Repeated missing external-weather acquisitions reduced the value of Open-Meteo as the primary reference for long-term joins and comparisons.

Open-Meteo was therefore removed as the main external-weather source.

This negative result is an important part of the experiment:

an API can be functionally usable but operationally unsuitable for a specific unattended long-term logging requirement.

6.4 Migration to other public observations

The final comparison used:

• regional meteorological data publicly released by an external research institution; and
• JMA AMeDAS observations.

The exact station/institution names and locations are withheld in the public record.

7. Dataset analysed

The API success rate was very high, but API success alone was not sufficient to guarantee a physically plausible measurement.

8. Analysis 1: indoor and outdoor temperature

Figure 1. Indoor and outdoor temperature time series.
Analysis period: approximately 2026-07-28 05:28 to 2026-08-13 21:28. Raw measurements at a nominal five-minute cadence were aggregated to hourly means. The plotted locations are outdoor, living room, crawl space, and attic. One physically implausible 0.0 °C living-room value was excluded from the temperature plot.

Representative statistics were:

The attic showed the largest thermal excursion and reached 44.3 °C.

The crawl space remained within a narrow 23.9–26.2 °C range.

The observed pattern is consistent with strong outdoor/solar forcing in the attic and substantial thermal buffering in the crawl space. These are interpretations of temperature observations, not direct heat-flux measurements.

9. Analysis 2: crawl-space relative and absolute humidity

9.1 Relative humidity

Figure 2. Mean diurnal relative humidity for outdoor air and the crawl space.
For the full analysis period, observations were grouped by hour-of-day (0–23) and averaged. The x-axis is hour-of-day; the y-axis is relative humidity [%RH].

Crawl-space relative humidity remained high throughout the day, with a period mean of approximately 86.9 %RH.

Outdoor relative humidity changed much more strongly with daytime temperature.

9.2 Absolute humidity

Figure 3. Mean diurnal absolute humidity for outdoor air and the crawl space.
For the full analysis period, observations were grouped by hour-of-day (0–23) and averaged. The x-axis is hour-of-day; the y-axis is absolute humidity [g/m³].

Period means were:

The crawl space had much higher relative humidity but almost the same mean absolute humidity as outdoor air.

Therefore, the high crawl-space %RH should not automatically be interpreted as a large excess of water vapour.

The lower crawl-space temperature substantially increases relative humidity for a similar vapour concentration.

This does not prove that condensation or mould risk is absent. Surface temperature, dew point, rainfall, ventilation, ground moisture, and material moisture would be required for a more complete risk assessment.

10. Analysis 3: living-room CO₂

Figure 4. Living-room CO₂ time series.
Analysis period: approximately 2026-07-28 05:28 to 2026-08-13 21:28. Measurements at a nominal five-minute cadence were aggregated to hourly means. Horizontal lines at 1000 ppm and 1500 ppm are reference lines to assist interpretation.

Summary statistics were:

Most observations were comparatively low, but temporary peaks were clearly present.

CO₂ can contain information related to occupancy, window opening, mechanical ventilation, cooking, and other indoor-air events.

Future work should pair environmental measurements with actual event annotations before making causal claims.

Supplementary diurnal CO₂ profile

Supplementary Figure 4b. Mean and 95th-percentile CO₂ by hour-of-day.
The full analysis period was grouped by hour-of-day (0–23). This aggregate allows time-of-day tendencies to be inspected without publishing the raw household time series.

11. Analysis 4: household outdoor sensor versus external observations

Figure 5. Temperature comparison between the household outdoor sensor and external observations.
SwitchBot outdoor data and two public external observation sources were aggregated to hourly means. Exact station names are anonymized.

The comparison produced:

The household outdoor sensor tracked the regional weather changes closely.

The systematic mean offsets should not automatically be interpreted as sensor calibration error.

Possible contributors include:

• different observation locations;
• sensor height;
• radiation from walls or paved surfaces;
• solar shielding;
• local airflow;
• household-scale microclimate.

The external observations and household sensor represent different spatial scales and can be used as complementary references.

12. Data-quality finding: SUCCESS does not guarantee a plausible measurement

A living-room temperature of 0.0 °C appeared in the private dataset even though its API response state was SUCCESS.

This demonstrates that two validation layers are required.

Transport/API validity

• Did the HTTP request succeed?
• Did the SwitchBot API return the expected status?
• Was the response structurally valid?

Measurement plausibility

• Is the temperature physically plausible for the installation?
• Is humidity within a valid range?
• Is CO₂ plausible for the device/environment?
• Is the change consistent with neighbouring time-series values?

The raw private record should be retained for auditability while analysis datasets receive separate quality flags.

13. Discussion

13.1 Why multi-location sensing matters

A single indoor temperature cannot represent the thermal behaviour of the attic, crawl space, conditioned rooms, and outdoor environment.

The measured zones showed clearly different responses:

• attic: strong outdoor/solar response;
• crawl space: strong thermal buffering;
• living room: comparatively stable;
• household outdoor sensor: regional weather response plus local microclimate.

13.2 Why relative humidity alone is insufficient

A crawl-space mean of approximately 86.9 %RH appears alarming if considered alone.

Absolute humidity changed the interpretation: crawl-space and outdoor mean water-vapour concentrations were very similar.

For building-moisture analysis, temperature, relative humidity, and an absolute moisture metric such as absolute humidity or dew point should be considered together.

13.3 Value of a household outdoor sensor

The high correlations with external observations show that the household outdoor sensor followed regional weather changes.

The remaining average offset may contain real household-scale microclimate information.

For building thermal analysis, both a regional reference and a site-specific outdoor measurement are useful.

13.4 External API operational requirements

The Open-Meteo experiment showed that long-term loggers must evaluate more than API functionality.

Important operational criteria include:

• request limits;
• missing-data behaviour;
• retry/retrieval capability;
• service continuity;
• unattended-operation reliability.

API behaviour is part of the experimental system specification.

14. Limitations

1. The analysed period is only about two summer weeks and does not represent annual behaviour.
2. The sensors were not calibrated against traceable reference instruments in this experiment.
3. Attic solar loading was inferred from temperature patterns; roof-surface temperature and heat flux were not directly measured.
4. Crawl-space moisture analysis did not include surface temperature, material moisture, or ground moisture.
5. CO₂ peaks were not paired with verified occupancy or ventilation events.
6. The relative contributions of sensor bias and local microclimate to the external-station temperature offset remain unresolved.
7. Raw household time-series data are withheld for privacy.

15. Follow-on analyses enabled by this dataset

15.1 Thermal lag and building time constants

Cross-correlation between outdoor temperature and each building zone can estimate response delays and characterize thermal inertia.

15.2 Solar influence on the attic

Solar irradiance, outdoor temperature, and attic temperature can be modelled together to separate ambient-air forcing from roof solar gains.

15.3 Crawl-space condensation risk

Temperature and absolute humidity can be converted to dew point and compared with foundation/floor/surface temperatures.

15.4 Ventilation analysis

CO₂ rise and decay can be paired with verified ventilation events and, under appropriate assumptions, used to estimate effective air-change rates.

15.5 Room-to-room comparison

Longer-term data can identify zones that are consistently warmer, cooler, more humid, or more variable.

15.6 Seasonal analysis

A full year would allow comparisons among humid summer, dry winter, rainy-season, and intermediate conditions.

15.7 Anomaly detection

Once normal daily and seasonal behaviour is established, deviations may help detect sensor failures, HVAC problems, unusual ventilation, or moisture anomalies.

16. Future integration with household energy measurements

Adding appliance and HVAC electricity data to the same timeline would enable analysis of:

external weather
  ↓
indoor temperature / humidity / CO₂
  ↓
HVAC, hot-water, and equipment operation
  ↓
electricity consumption

The useful question then becomes not only:

“How much electricity was used?”

but:

“How much electricity was required to maintain a given indoor environment under a given outdoor condition?”

17. Implementation lessons

1. Store the derived moisture variable that later analysis will require; absolute humidity materially improved interpretation.
2. Validate device types against the real API inventory.
3. Per-device exception handling helps prevent one endpoint failure from creating a whole-system data gap.
4. LockService protects a frequent scheduled logger from overlapping executions.
5. Caching the device inventory reduces unnecessary API traffic.
6. API success and physical measurement plausibility require separate validation.
7. External APIs should be evaluated for operational continuity, not only for functional availability.
8. Household outdoor measurements and regional weather observations describe different spatial scales and should be treated as complementary.
9. Raw household telemetry does not need to be public to preserve technical value; aggregation methods, summary statistics, plots, and implementation details can support reuse while protecting privacy.

18. Reproducibility boundary

A similar implementation can be reproduced with:

• owned SwitchBot environmental sensors;
• SwitchBot OpenAPI v1.1 credentials;
• Google Apps Script;
• HMAC-SHA256 authentication;
• a nominal five-minute time-driven trigger;
• separate Measurements, Devices, Logs, and Settings tables;
• absolute-humidity calculation;
• per-device exception handling;
• LockService;
• an external weather source appropriate to the local deployment;
• explicit data-quality handling during analysis.

Credentials, private household labels, device identifiers, raw household telemetry, and exact external station locations are intentionally excluded because they are not required to reproduce the technical architecture.

19. Summary

Using SwitchBot environmental sensors as a continuous time-series source rather than only as a current-value display created a useful residential environmental dataset.

Even a short summer dataset revealed strong attic thermal response, stable crawl-space temperature, high crawl-space relative humidity without a comparable excess in absolute humidity, transient living-room CO₂ peaks, and strong agreement between the household outdoor sensor and independent weather observations.

Operational failures were equally valuable findings: initial environmental-device filtering missed some sensors, Open-Meteo did not provide sufficient unattended continuity for the intended use, and an API SUCCESS state did not guarantee a physically plausible value.

For an AI Experiment Log, the useful artifact is therefore not only the final working configuration but the complete chain of attempt → failure → correction → measurement → analysis → interpretation → unresolved questions.