From 6d403d550cde49092499ae395d5a748874bcf5cd Mon Sep 17 00:00:00 2001 From: Ken Zangelin Date: Wed, 10 Jul 2024 14:45:48 +0200 Subject: [PATCH] Improved documentation --- README.md | 39 ++++++++++++++++++++------------------- doc/roadmap.md | 11 +++++------ 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 3bfd925414..db2ca706e9 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![Support badge](https://img.shields.io/badge/support-sof-yellowgreen.svg)](http://stackoverflow.com/questions/tagged/fiware-orion) [![NGSI-LD badge](https://img.shields.io/badge/NGSI-LD-red.svg)](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.08.01_60/gs_cim009v010801p.pdf)
-[![Documentation badge](https://readthedocs.org/projects/fiware-orion/badge/?version=latest)](http://fiware-orion-ld.readthedocs.io/en/latest/?badge=latest) +[![Documentation badge](https://readthedocs.org/projects/fiware-orion/badge/?version=latest)](http://fiware-orion.readthedocs.io/en/latest/?badge=latest) ![Status](https://nexus.lab.fiware.org/static/badges/statuses/incubating.svg) [![Coverage Status](https://coveralls.io/repos/github/FIWARE/context.Orion-LD/badge.svg?branch=develop)](https://coveralls.io/github/FIWARE/context.Orion-LD?branch=develop) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4800/badge)](https://bestpractices.coreinfrastructure.org/projects/4800) @@ -26,7 +26,7 @@ management, implementting both the [NGSI-LD API](https://en.wikipedia.org/wiki/N [Orion Context Broker](https://github.com/telefonicaid/fiware-orion) extending support to add **NGSI-LD** and linked data concepts. Orion-LD follows the [ETSI](https://en.wikipedia.org/wiki/ETSI) specification for **NGSI-LD** and has been tested to be a stable and fast **NGSI-LD** broker with near compliance to the version 1.6.1 of the NGSI-LD API -specification. +specification (and some features from newer releases). ## License @@ -54,7 +54,7 @@ wish to make a clarifying public statement as follows: ## Contribution to Orion-LD Anyone wishing to contribute to Orion-LD, be it fixing/adding documentation, tests, source code, all types of contributions are welcome. -For source code contributions, please see the [Contribution guidelines](doc/manuals/devel/contribution_guidelines.md). +For source code contributions, please see the [Contribution guidelines](doc/manuals/contribution_guidelines.md). ## General Information on NGSI-LD @@ -62,42 +62,42 @@ For source code contributions, please see the [Contribution guidelines](doc/manu Its payloads are encoded as [linked data](https://en.wikipedia.org/wiki/Linked_data) using JSON. The NGSI-LD Specification is regularly updated and published by ETSI. -The latest specification is [version 1.8.1](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.08.01_60/gs_cim009v010801p.pdf) -and it was published in March 2024. The next release, v1.9.1, is expected for November-December 2024 +The latest specification is [version 1.8.1](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.08.01_60/gs_cim009v010801p.pdf), published in March 2024. +The next release, version 1.9.1, is expected for September/October 2024ยท A few presentations on NGSI-LD: * [NGSI-LD Overview](https://docs.google.com/presentation/d/1tgh6gBdcZHRPU_ehM7M5rGCI83CrYimCwJXxzRI5GDg) -* [NGSI-LD in 30 min](https://docs.google.com/presentation/d/1z1IzikB7NxIkihDosV4KrtNS_IJUdrNiwC_b4wAI0rc/edit#slide=id.p1) -* [NGSI-LD in a nutshell](https://docs.google.com/presentation/d/14aoHGYzmfn_a31ByG_Tf8pejuP6oWhjqhraLsPtRp_k/edit#slide=id.p1) +* [NGSI-LD in 30 min](https://docs.google.com/presentation/d/1z1IzikB7NxIkihDosV4KrtNS_IJUdrNiwC_b4wAI0rc) +* [NGSI-LD in a nutshell](https://docs.google.com/presentation/d/14aoHGYzmfn_a31ByG_Tf8pejuP6oWhjqhraLsPtRp_k) Examples of **NGSI-LD** payloads can be found in [ETSI](https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/tree/master/examples). See also the [OpenAPI Specification of NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/ngsi-ld-api.yaml) -That is for v1.6.1 of the NGSI-LD API specification. +That is for version 1.7.1 of the NGSI-LD API specification. We're currently working on updating this to v1.8.1, ETA: Dec 2024. If you are not sharing your data across systems and have no need for linked data concepts, then the current stable version of **NGSI** (**NGSI-v2**) is more than sufficient. -If so, please use the original unforked [Orion](https://github.com/telefonicaid/fiware-orion) instead of Orion-LD (note that Orion-LD is **not** up-to-date with Orion in terms of NGSI v2). +If so, please use the original [Orion](https://github.com/telefonicaid/fiware-orion) instead of Orion-LD (note that Orion-LD is **not** up-to-date with Orion in terms of NGSI v2). -## NGSI-LD Context Broker Feature Comparison -An Excel file detailing the current compatibility of the development version of the Orion-LD Context Broker against the features of v1.6.1 of the API specification can be downloaded [here](https://docs.google.com/spreadsheets/d/18tq0_PZFl5WCfYUElcdI6M3Vlin4hP-M). - | :books: [Documentation](https://github.com/FIWARE/context.Orion-LD/tree/develop/doc/manuals-ld) | :mortar_board: [Academy](https://fiware-academy.readthedocs.io/en/latest/core/orion-ld) | [quay.io](https://quay.io/repository/fiware/orion-ld) | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +## NGSI-LD Context Broker Feature Comparison +An Excel file detailing the current compatibility of the development version of the Orion-LD Context Broker against the features (up to v1.8.1) of the API specification can be downloaded [here](https://docs.google.com/spreadsheets/d/18tq0_PZFl5WCfYUElcdI6M3Vlin4hP-M). + ## Test and Deployment of Orion-LD If you want to start testing Orion-LD, the most common option is to use Docker. There are a number of docker images to choose from. If you (at your own risk) want to evaluate the bleeding edge development changes, you can use the latest image: -`docker run fiware/orion-ld:latest` or even better: use +`docker run fiware/orion-ld:latest` or better: use [docker compose](https://github.com/FIWARE/context.Orion-LD/blob/develop/docker/docker-compose.yml) to run it. The use of the "latest" tag is NOT RECOMMENDED, as it keeps changing. Please don't use it. It's solely meant for internal testing. -Thge recommendation is to use the newest fixed tag you find and stick to it until you have need for some newer feature/fix and then change to that newer fixed tag. -Every merged pull request results in a new fixed tag in dockerhub. +The recommendation is to use the newest fixed tag you find and stick to it until you have need for some newer feature/fix and then change to that newer fixed tag. +Every merged pull request results in a new fixed tag in dockerhub/quay.io. Please note that for production and/or performance implementations, there is a thorough guide for that right [here](https://github.com/FIWARE/load-tests) @@ -119,13 +119,14 @@ Please check [quay.io](https://quay.io/repository/fiware/orion-ld?tab=tags) for - [Temporal Representation](doc/manuals-ld/troe.md) - [The Broker as Context Server](doc/manuals-ld/contextServer.md) - [State of the Implementation](doc/manuals-ld/implementationState.md) -- [Roadmap](roadmap.md) +- [Roadmap](doc/roadmap.md) - [Planning - Issue #280](https://github.com/FIWARE/context.Orion-LD/issues/280) A Test Suite for NGSI-LD compliant brokers can be found [here](https://github.com/fiware/NGSI-LD_Tests). This test suite is deprecated in favor of the newer [ETSI NGSI-LD API Conformance Test Suite](https://forge.etsi.org/rep/cim/ngsi-ld-test-suite). (Orion-LD passes about 95% of the test cases of this older deprecated test suite.) -About the ETSI funded conformance test suite, a third TTF (Testing Task force) is currently in progress, to aggregate conformance tests for distributed operations. -The TTF is expected to finish in February 2025 and by then we expect the ETSI NGSI-LD conformance test suite to be fully operational, and thus test results for Orion-LD -can and will be published. +About the ETSI funded conformance test suite, a third TTF (Testing Task force) is currently in progress, to improve on overall coverage and to +aggregate conformance tests for distributed operations. +This third TTF is expected to finish in February 2025 and by then, the ETSI NGSI-LD conformance test suite should be fully operational, +and thus test results for Orion-LD can and will be published. diff --git a/doc/roadmap.md b/doc/roadmap.md index 917240ecb2..6bd1f29323 100644 --- a/doc/roadmap.md +++ b/doc/roadmap.md @@ -4,11 +4,10 @@ This product is a FIWARE Incubated Generic Enabler. If you want to learn about the overall Roadmap of FIWARE, please have a look at the section "Roadmap" in the FIWARE Catalogue. ## Short/Medium Term Roadmap -* Implement the new registrations, as of NGSI-LD API v1.6.1 -* Registration-Cache for better performance -* Implement forwarding using the new registrations, tentative order of first requests: - - GET /entities - - PATCH /entities/{entityId} -* Memory management for containers - for a better experience with Orion-LD inside containers +* Distributed subscriptions +* Native DDS support +* GEOS for the subscription cache (geolocation without need of DB) +* New Implementation of the Subscription Cache +* New NGSI-LD-Only Orion-LD (using the new logging library) For Medium/Long term planning, please refer to the [Issue #280](https://github.com/FIWARE/context.Orion-LD/issues/280)