Skip to main content

Search

KNX Device Development

Information about KNX device development

      Manufacturer's Catalog Item Resolution

      Vassilios Lourdas
      • Updated

      Manufacturer’s Catalog Item Resolution maps serial numbers and GTINs to catalog items through KNX-hosted mappings or HTTPS service endpoints. MyKNX lets manufacturers create endpoints, add or import rules, understand resolution order, and check identifiers.

      ✨This content was created using AI.

      This article covers the following topics:

      Introduction

      Manufacturer's Catalog Item Resolution is a MyKNX function for KNX manufacturers. It defines how the serial numbers (SN) and GTINs of your devices are resolved to catalog items, for example when a device is scanned in ETS. For each range of identifiers you choose one of two options:

      • KNX-hosted mapping: KNX stores the mapping and returns the catalog item you selected.
      • Forward to your service: the lookup is forwarded to an HTTPS endpoint operated by you, which returns the catalog item.

      Without resolution rules, your serial numbers and GTINs cannot be resolved to catalog items.

      How an identifier is resolved

      When a serial number or GTIN is looked up, the rules are evaluated in this order:

      1. SN or GTIN is looked up, for example when a device is scanned in ETS.
      2. Your service rules are checked first. If the identifier matches the range of a service rule, the request is forwarded to your endpoint.
      3. KNX-hosted mappings are the fallback. If no service rule matches and a KNX-hosted mapping matches, KNX returns your catalog item.
      4. Not resolved. If no rule matches, no catalog item is returned.

      You can also see this explanation in MyKNX by clicking on "How an identifier is resolved".

      How to open Catalog Item Resolution

      1. Log in to MyKNX and select your company in the organization selector.
      2. Go to "Account" and, in the "Member" column, click on "Manufacturer's Catalog Item Resolution".

      The page lists your existing rules. You can filter them by rule type ("All rules", "Your service", "KNX-hosted") and by identifier ("SN and GTIN", "SN", "GTIN"), or search by range, catalog item or endpoint.

      How to add a service endpoint

      An endpoint is only needed if you want to forward lookups to your own service. Define an endpoint once and reuse it in several service rules.

      1. In the "Your service endpoints" box, click on "Add endpoint".
      2. Enter a Name for your team, e.g. "Production service" or "Staging".
      3. Enter the Endpoint: an HTTPS URL that receives the same query as the public endpoint (?sn= or ?gtin=) and returns the same response.
      4. Click on "Save".

      How to add a resolution rule

      1. Click on "Add rule".
      2. Under 1 · Which identifiers, select the Identifier: "Serial number (SN)" or "GTIN".
      3. Select the Range:
        • Min/Max: enter the lower and upper bound (inclusive). For SN the format is the manufacturer code followed by 8 hex digits (MMMM:HHHHHHHH). For GTIN enter up to 14 digits; shorter GTINs are normalized automatically.
        • Wildcard: enter a pattern in which question marks (?) match any character, e.g. 00FA:0000????.
        • All of my serial numbers: covers all serial numbers of your manufacturer code (SN only).
      4. Under 2 · How they are resolved, choose:
        • KNX-hosted mapping and select the Catalog item (start typing to search by product name or catalog item ID), or
        • Forward to your service and select the Endpoint.
      5. Click on "Save".

      To forward to your service, an endpoint must exist first. If none is defined, close the dialog, add an endpoint under "Your service endpoints" and then create the rule again.

      How to import rules from a CSV file

      To create many rules in one step, click on "Import CSV". Each row maps serial numbers or GTINs to a catalog item, or forwards the lookup to one of your service endpoints. The file must be UTF-8, comma separated and contain a header row. You can download a template from the import page ("Download the template CSV").

      Column Required Allowed values Description
      identifier Yes SN, GTIN Identifier type the rule applies to.
      range_type Yes min_max, wildcard, all all (all of my serial numbers) is only valid for SN.
      min / max When range_type is min_max SN: MMMM:HHHHHHHH · GTIN: 1–14 digits Lower and upper bound, inclusive. Shorter GTINs are normalized to 14 digits.
      wildcard When range_type is wildcard SN: MMMM:HHHHHHHH with ? · GTIN: 14 characters with ? Question marks (?) match any character of the range.
      resolution_type Yes hosted, forward KNX-hosted mapping or forward to your service.
      catalog_item_id When resolution_type is hosted An existing catalog item ID Target for hosted rules.
      endpoint_name When resolution_type is forward The name of an existing endpoint Target for forward rules.

      Columns that do not apply to the chosen range_type or resolution_type must be left empty. Endpoints are created under "Your service endpoints", not by CSV. The import only adds rules; existing rules are never modified.

      How to check an identifier

      Use the "Check an identifier" box to see which rule applies before a device reaches the field. Enter a serial number (e.g. 00FA:00000007) or GTIN and click on "Check". The result shows the matching rule, or "Not resolved" if the identifier matches no rule.

      Related articles

      Didn't find what you were looking for?
      Community