udmi

UDMI / Docs / Guides / Development

Development

Schema Documentation

The schema documentation in gencode/docs must be kept up to date with any changes to the schema. Any additions to the schema should also include annotations to describe the new elements. The updated documentation is generated by running the script bin/gendocs and its output committed to the repository with the changes. Required python dependencies are in etc/requirements.txt which must be installed for the script to run.

Troubleshooting

If documentation CI tests are failing, check the basic system requirements - python modules installed and matching versions in etc/requirements.txt, and GNU variants sed and find. An unsupported system will generate documentation with changes, even when the underlying schema has not changed. gendocs works best under Linux.

New schema files should automatically receive an entry in the index gencode/docs/readme.md file if they are not referenced by any other schema file. If a schema file is referenced by another schema file, but should still have an entry in the index page, then the name should be added to the to the ALWAYS_ROOT list in bin/gencode_root_schemas.

Entries in the index gencode/docs/readme.md page sectioned according to the value of $section in the schema file. The section must also exist in the template etc/schema_readme_template.md, and must match (case sensitive) the value of $section, otherwise the schema entry is inserted under the Other section

Releases

The bin/upgrade_version tool updates :

• the $udmi_version field in schema files,
• the version in version in tests/**/*.json according to manually curated file
• documentation inline message examples.
• the UDMI_VERSION constant in specific JAVA files.

File in the tests directory must be listed in etc/upversion.txt. Only files which are preceded by a y in upversion.txt will have their version upgraded. Comments are supported after the file path, e.g. y tests/schemas/state/makemodel_upgrade.json tests message upgrade from v1

bin/upgrade_version carries out several checks on files which must be cleared before an update.

bin/upgrade_version does not update any generated files (e.g. for CI testing).

The below files need to be updated. Do not blindly copy! Inspect all diffs and confirm they are expected

• After bin/test_trace simple, contents of sites/udmi_site_model/sites/out into tests/traces/simple/expected
• After bin/test_validator, /tmp/validator.out into /etc/validator.out (reset any changes to sites/udmi_site_model before running but run bin/registrar)
• After bin/test_registrar && bin/test_sites, the out directory for each device in tests/downgrade.site/devices/ into the expected subdirectory (note these files are ignored by git, but must still be committed)

Configuring Cloud CI Tests

To enable the CI tests, there first needs to be a dedicated GCP Project with an IoT Core registry which mirrors the example site model. A Github variable must also configured to point to the GCP project

They key steps to setup the dedicated project are as follows:

1. Setup up a GCP Project and IoT Core Registry. The cloud setup and UDMIS (cloud functions) setup documents give guidance on this. If GCP Cloud SDK and re-authentication may be required. The registry name and cloud region are as follows:
   • Registry Name: ZZ-TRI-FECTA
   • Cloud Region: us-central1
2. Setup the site model by cloning the example site model in the udmi root directory and running the registrar tool to configure the site model in the IoT Core Registry.
   • git clone https://github.com/faucetsdn/udmi_site_model.git
   • bin/registar <GCP_PROJECT_ID> udmi_site_model
3. Set up the sequence tests. The public key used for the virtual device in the IoT Core registry is the public key from udmi_site_model/devices/AHU-1/rsa_public.pem. A validator_config.json configuration file is not needed (this is generated automatically during the CI test)
   • The registry name is ZZ-TRI-FECTA.
4. A Github variable needs to be added to the project, accessed from the project’s Settings page.
   • Name: GCP_TARGET_PROJECT
   • Value: GCP Project ID
5. Enable Github Actions

The workflow can be tested with an empty commit (git commit --allow-empty -m "Blank commit to trigger CI"; git push). On an unmodified branch, these tests should pass if correctly configured

This site is open source. Improve this page.