GreenSparks
Login

Support

Engineering Guide

Expert guidance for configuring GreenSparks device specifications, validating Engineering JSON, testing live readings, and diagnosing telemetry setup.

Purpose and Audience

Engineering surfaces are for people who configure how GreenSparks talks to devices and turns raw responses into named measurements. Most users should work in Venues, Events, Devices, Readings, Maps, and Reports. Use Engineering when a category, product, or device needs telemetry setup, integration details, schema correction, or a live reading test.

Treat Engineering edits as operational configuration. A small JSON change can alter whether readings are collected, which units appear in reports, and whether downstream users see useful status. If you are not sure what a field does, validate the JSON first, test in a local or development environment, and record the gap before changing production-like data.

Engineering Concepts

GreenSparks models device setup in three layers. A category describes a broad device family or measurement domain. A product, also called a template in some technical surfaces, describes a reusable device type. A device, also called an instance, represents one configured item that can be assigned to an operating context and used for readings or reports.

  • Category JSON can define measurement categories such as energy-related telemetry.
  • Product or template JSON usually defines reusable transport, endpoint, authentication, request steps, and extraction rules.
  • Device or instance JSON usually defines device-specific endpoint, authentication, runner, identity, or override details.
  • Readings are created after GreenSparks combines the relevant specification layers into query context and attempts data collection.
  • Reports, maps, zones, and event views depend on this setup being clear enough for measurements to be interpreted consistently.

Environment matters. A Test button run from a local app should call the local API, which may in turn use local proxy routes such as /ha/. A production-pointed app can test against different data and integrations. If a result looks surprising, confirm the active app and API environment before changing JSON.

JSON Specification Model

Engineering descriptions are stored as JSON. The editor checks both plain JSON syntax and the GreenSparks model for the selected surface. Unknown fields are rejected for the currently modeled category, template, and instance shapes, so spelling and placement matter.

Category JSON

Category JSON must include a name. It may include measurement_categories, where each item has a stable key, a user-facing label, and optionally a description. Use this layer for broad measurement groupings, not per-device endpoint details.

Product or Template JSON

Product or template JSON must include a name. HTTP-style templates can describe transport_type, endpoint, authentication, response_grouping, and request steps or legacy paths. Each step can define a request path, mark itself as primary, provide identity or parameter values, and list extraction rules.

Modbus TCP templates use a different shape. They define register blocks and a decode map that explains how values are read from those blocks. The current schema supports holding and input register reads, boolean and unsigned 32-bit big-endian decoding, scaling, signed values, sentinel values, units, and categories.

Device or Instance JSON

Device or instance JSON usually contains the values that vary from one physical or logical device to another. For HTTP-style instances, this can include endpoint, authentication, response grouping, request steps, and a collection runner. For Modbus-style instances, it includes an endpoint and can include device details such as register base or serial number.

Extraction Rules

Extraction rules turn a response into named measurements. Each extraction item requires a key, type, and path. The unit and category fields are optional but important for readable results. Use stable keys that will make sense when they appear in readings, reports, or troubleshooting output.

The current value types include string, number, { string }, [ string ], and [ number ]. Identity items may also declare valueType, which is useful when the integration needs a typed identity value rather than an unlabelled literal.

Starting From Skeleton JSON

New Engineering records are no longer blank. GreenSparks provides a skeleton that passes the current schema and gives the editor a useful starting structure. Replace placeholders with real values before relying on a Test result.

Category Skeleton

  • Keep the generated name aligned with the category name.
  • Review the default energy-measurement category and rename or extend it only when the category truly needs different groupings.
  • Use labels and descriptions that a later report reader can understand.

Product or Template Skeleton

  • Replace https://example.com with the real base URL or proxy path strategy.
  • Replace the sample /status path with the request path that returns telemetry.
  • Replace the sample Power extraction with the real response path, type, unit, and category.
  • Change authentication from none only when the integration actually requires query-string, header, OAuth, AWS JWT, or token exchange behavior.

Device or Instance Skeleton

The instance skeleton is deliberately smaller. It gives a name, transport type, endpoint, and authentication object. Add device-specific values that distinguish this instance from others of the same product. Avoid copying product-level request and extraction rules into every instance unless the device really needs an override.

Inline Validation

The Engineering editor uses inline markers for both JSON parse failures and GreenSparks schema failures. Syntax errors show where the JSON itself is invalid. Schema errors show where valid JSON does not match the model for categories, templates, or instances.

  • If punctuation, braces, commas, or quotes are wrong, fix the JSON syntax before looking for deeper model problems.
  • If a field is underlined as unexpected, check whether it belongs at a different layer or whether the schema does not yet model that concept.
  • If a required field is missing, add the smallest correct field rather than padding the object with unrelated values.
  • If a value has the wrong type, decide whether the integration value should be converted or whether the declared type or valueType is wrong.

The Validate button still matters. Use it to get an explicit success or failure message before saving or testing. A successful validation means the JSON is well-formed and matches the current model; it does not prove that the device is online or that the integration will return data.

Validate and Test

Validate and Test answer different questions. Validate asks: "Is this JSON structurally acceptable?" Test asks: "Can GreenSparks use the saved configuration to attempt a live reading?"

  • Validate before saving or testing any substantial change.
  • Save the entity before running Test, because Test runs against saved configuration.
  • Test refreshes query context for the selected instance, template, or category scope.
  • For an instance, Test refreshes and tests that instance's query context.
  • For a template, Test refreshes query contexts for devices using that template.
  • For a category, Test refreshes templates in the category and tests the resulting query contexts.

Test results appear in the same message area as Validate results. A successful test reports status counts and, when available, a latest reading with measurement keys, values, and units. A failed or partial test may still be useful: it can show that the JSON validates but the device is unavailable, offline, unreachable, misrouted, or returning an unexpected response.

Device Integration Patterns

The first supported Engineering patterns are intentionally practical. HTTP integrations describe endpoints, authentication, request steps, and extraction paths. Modbus TCP integrations describe blocks and decode rules. Some devices may be reached through a local proxy route, while others may use a direct endpoint or an agent-backed path.

Home Assistant and Proxy Paths

GreenSparks can use proxy-style paths such as /ha/ when a local backend mediates access to Home Assistant. Do not assume that a path starting with /ha/ should be sent directly to the Home Assistant host. In local testing, that path belongs to the Inventory API proxy behavior.

HTTP and REST Devices

For HTTP devices, start by confirming the request path and response shape outside the editor if possible. Then encode only the stable parts in the product/template. Put per-device endpoint, identity, or credentials in the instance when those values vary by device.

Modbus TCP Devices

For Modbus TCP devices, keep register reads grouped into clear blocks. Use decode rules to name measurements, apply scaling, and identify units. If a register map is uncertain, document the uncertainty and support the clean subset first.

Example Device Families

Smart plugs such as Eightree and Tapo-style devices are useful examples because they quickly show whether power, current, voltage, and energy values are being extracted correctly. Battery, UPS, and power-distribution equipment often need more careful modeling because status, capacity, output, and energy fields can have different units and reporting intervals.

Troubleshooting

Work from the smallest failing layer upward. A live reading cannot succeed until JSON parses, the GreenSparks schema accepts it, the entity is saved, query context can be refreshed, and the target device or integration is reachable.

  • Invalid JSON: fix syntax first. Formatting can help expose unmatched braces or trailing commas.
  • Schema failure: compare the underlined field with the category, template, or instance model. Move misplaced fields to the correct layer.
  • No query context: save the entity and confirm the selected category, template, or instance has enough configuration to generate a query.
  • API 404 or routing issue: confirm the frontend is pointed at the API environment you intend to test.
  • Unavailable or offline device: confirm power, network, integration visibility, and credentials before changing extraction rules.
  • Empty or partial measurements: check the response path, type, unit, and category. A request can succeed while an extraction rule still points at the wrong value.
  • Repeated per-device fixes: consider whether the product/template model is wrong and should be corrected once for the device family.

Quality and Release Checklist

Before treating Engineering setup as ready for broader use, check both the JSON and the operational behavior it drives.

  • Specification validates without syntax or model errors.
  • Required placeholders have been replaced with real values.
  • The entity has been saved after validation.
  • Engineering Test retrieves representative live measurements.
  • Measurement keys are stable and readable.
  • Units are present where users need them to interpret values.
  • Categories match the reporting or diagnostic meaning of the measurement.
  • The tested environment is the intended environment.
  • Known device limitations are documented as notes or future stories.

Future Topics

This guide will become more useful as Engineering gathers more examples and the product formalizes expected measurement profiles. The next documentation pass should add screenshots, copyable examples, and device-family recipes.

Likely future sections include compliance or completeness scoring for Engineering specifications, expected measurement profiles for categories and products, reusable examples for common device families, migration guidance when schemas evolve, and admin controls for Engineering access and approval workflows.