diff --git a/.github/workflows/algolia.yml b/.github/workflows/algolia.yml new file mode 100644 index 00000000..578ed399 --- /dev/null +++ b/.github/workflows/algolia.yml @@ -0,0 +1,51 @@ +name: Algolia Push + +#tmp just for developing +on: + push: + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + # fetch branches and history so `git merge-base` in check-format-on-diff works correctly + fetch-depth: 0 + - uses: actions/setup-go@v5 + with: + go-version: "^1.20" # The Go version to download (if necessary) and use. + check-latest: true + + - name: Install npm dependencies + run: npm install -g --legacy-peer-deps hugo-algolia + + - name: Check if hugo-algolia is installed + run: hugo-algolia --version + + - name: Generate algolia.json + run: | + mkdir -p public + hugo-algolia --config config/_default/config.yaml + + - name: Build Go binary + run: | + cd tools/adjust-algolia-output + go build -o /usr/local/bin/adjust-algolia-output + + - name: Adjust algolia.json using binary + run: adjust-algolia-output < ./public/algolia.json | jq > public/algolia_final.json + + - name: Install Node.js + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: Push to Algolia + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + run: | + cd scripts + npm install algoliasearch + APPLICATION_ID=${{ secrets.ALGOLIA_APPLICATION_ID }} API_KEY=${{ secrets.ALGOLIA_API_KEY }} node push-to-algolia.js ../public/algolia_final.json diff --git a/.gitignore b/.gitignore index cfe03ca2..c28eaac1 100644 --- a/.gitignore +++ b/.gitignore @@ -14,4 +14,5 @@ nohup.out trace.out .idea node_modules -.hugo_build.lock \ No newline at end of file +.hugo_build.lock +adjust-algolia-output \ No newline at end of file diff --git a/config/_default/config.yaml b/config/_default/config.yaml index f38563ca..5c8a8cd7 100644 --- a/config/_default/config.yaml +++ b/config/_default/config.yaml @@ -3,6 +3,7 @@ baseURL: 'https://docs.plgd.dev/' theme: 'plgd' title: 'plgd docs' defaultContentLanguage: en +defaultContentLanguageInSubdir: false enableEmoji: true footnotereturnlinkcontents: ↩ languageCode: en-us @@ -17,9 +18,6 @@ languages: # weight: 2 copyright: 'All Rights Reserved © 2020-{year} plgd.dev, s.r.o.' googleAnalytics: 'GTM-5B8C4RK' -algolia: - index: "doc" - appID: "42D6VHXINQ" pluralizeListTitles: false outputs: home: @@ -27,6 +25,7 @@ outputs: - RSS - REDIR - HEADERS + - ALGOLIA section: - HTML - RSS @@ -44,6 +43,15 @@ outputFormats: baseName: _headers isPlainText: true notAlternative: true + Algolia: + baseName: "algolia" + isPlainText: true + mediaType: "application/json" + notAlternative: true + JSON: + mediaType: "application/json" + baseName: "data" + isPlainText: true caches: getjson: dir: ':cacheDir/:project' @@ -75,4 +83,8 @@ taxonomies: category: categories params: githubRepository: 'https://github.com/plgd-dev/doc/' + algolia: + indexName: 'doc' + apiKey: '31dbe24685b8a1a7025c12098b32df37' + appId: '42D6VHXINQ' --- \ No newline at end of file diff --git a/content/en/docs/deployment/device-provisioning-service/advanced.md b/content/en/docs/deployment/device-provisioning-service/advanced.md index bdf1bb22..2f4ea270 100644 --- a/content/en/docs/deployment/device-provisioning-service/advanced.md +++ b/content/en/docs/deployment/device-provisioning-service/advanced.md @@ -47,43 +47,43 @@ In the process of acquiring a device access token from the OAuth server, the Dev 1. Create an OAuth client for DPS in KeyCloak with the following configuration: - Settings: - - Enabled: On - - Client Protocol: openid-connect - - Access Type: confidential - - Service Accounts Enabled: On - - Authorization Enabled: On + - Enabled: On + - Client Protocol: openid-connect + - Access Type: confidential + - Service Accounts Enabled: On + - Authorization Enabled: On - Credentials: - - Client Authenticator: Client Id and Secret - - Secret: `` + - Client Authenticator: Client Id and Secret + - Secret: `` - Mapper: - - Create a custom `Hardcoded claim` mapper: - - Token Claim Name: `` - - Claim value: `` - - Claim JSON Type: String - - Add to access token: On - - Add to userinfo: On + - Create a custom `Hardcoded claim` mapper: + - Token Claim Name: `` + - Claim value: `` + - Claim JSON Type: String + - Add to access token: On + - Add to userinfo: On 2. Create a WWW OAuth client with a mapper that adds the `` claim to the user JWT token. You can use the `User Property` mapper with the following configuration to map the `id` property to the `` claim: - Settings: - - Enabled: On - - Client Protocol: openid-connect - - Access Type: public - - Standard Flow Enabled: On - - Valid Redirect URIs: `[ https://www.example.com/*,... ]` - - Backchannel Logout Session Required: On - - OpenID Connect Compatibility Modes: - - Use Refresh Tokens: On + - Enabled: On + - Client Protocol: openid-connect + - Access Type: public + - Standard Flow Enabled: On + - Valid Redirect URIs: `[ https://www.example.com/*,... ]` + - Backchannel Logout Session Required: On + - OpenID Connect Compatibility Modes: + - Use Refresh Tokens: On - Mapper: - - Property: id - - Token Claim Name: `` - - Claim JSON Type: String - - Add to ID token: On - - Add to access token: On - - Add to userinfo: On + - Property: id + - Token Claim Name: `` + - Claim JSON Type: String + - Add to ID token: On + - Add to access token: On + - Add to userinfo: On In the helm chart, add the following configuration: diff --git a/content/en/docs/deployment/hub/advanced.md b/content/en/docs/deployment/hub/advanced.md index ba60c907..bb5bfeef 100644 --- a/content/en/docs/deployment/hub/advanced.md +++ b/content/en/docs/deployment/hub/advanced.md @@ -181,7 +181,7 @@ certmanager: cert: duration: 876000h # 100 years for intermediate CA used to sign device certificates ca: # CA to signing services(in default) and device certificates - issuerRef: + issuerRef: kind: "ClusterIssuer" # or "Issuer" name: "plgd-ca-issuer" group: cert-manager.io diff --git a/content/en/docs/features/monitoring-and-diagnostics/disaster-recovery.md b/content/en/docs/features/monitoring-and-diagnostics/disaster-recovery.md index 0f002c3c..5530c35c 100644 --- a/content/en/docs/features/monitoring-and-diagnostics/disaster-recovery.md +++ b/content/en/docs/features/monitoring-and-diagnostics/disaster-recovery.md @@ -61,7 +61,7 @@ The plgd hub is a stateful event-driven system, meaning that data is stored in t To back up the database, two approaches can be used: * **Passive Backup** - + ![passive-backup](/docs/features/monitoring-and-diagnostics/static/disaster-recovery-passive-backup.drawio.svg) The database is regularly backed up to a different location and can be used in case of failure. Although this approach is simple and requires fewer resources, the data may become outdated, and the restoration process may take some time. For MongoDB, utilize the `mongodump` tool to create a export of the database contents, store it securely, and use it in case of failure. Regular backups are essential to keep the data up-to-date. For more details on this approach, refer to the [MongoDB documentation](https://www.mongodb.com/docs/database-tools/mongodump/). @@ -93,11 +93,11 @@ The CoAP-Gateway and Device Provisioning Service depend on certificates validate If a primary cluster failure occurs and you cannot dynamically modify the endpoint on the devices, they will be unable to establish a connection with the hub. Devices are set up with a single endpoint to link with either the CoAP-Gateway or the Device Provisioning Service, which may include an IP address or DNS address. To guarantee connectivity to the secondary cluster, adopt one of the provided options: * **DNS Address as endpoint** - + In case of primary cluster failure, update the DNS record on the DNS server. It is recommended to set the time to live (TTL) of the DNS record to a low value, e.g., 30 minutes. * **IP Address as endpoint** - + ![load-balancer](/docs/features/monitoring-and-diagnostics/static/disaster-recovery-load-balancer.drawio.svg) Changing the IP address could be challenging in case of primary cluster failure, as the public IP address is often assigned to the Internet Service Provider (ISP). However, using an IP load balancer near devices allows changing the IP address of the load balancer to the secondary cluster. For this, you can use HAProxy, which supports layer 4 load balancing. For more information, refer to the [HAProxy documentation](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/load-balancing/tcp/) and [Failover & Worst Case Management With HAProxy](https://www.haproxy.com/blog/failover-and-worst-case-management-with-haproxy). @@ -105,13 +105,12 @@ If a primary cluster failure occurs and you cannot dynamically modify the endpoi * **Update Device Provisioning Service endpoint** Under these circumstances, you have the option to update the DPS endpoint to the secondary cluster by utilizing the DHCP server to supply the devices with the updated endpoint. The device retrieves a new configuration from the DPS service, obtaining updated: - * Time(optional) * Owner * Credentials - Identity certificate, root CA certificate and Pre-shared key(optional) * Access control lists (ACLs) * Cloud configuration - Authorization code, Hub ID, Hub URL, etc. - + Subsequently, the module connects to the cloud, with the first operation being to sign up for self-registration. **From the Hub perspective:** diff --git a/content/en/docs/tutorials/dashboard-branding.md b/content/en/docs/tutorials/dashboard-branding.md index 2c2d8dbf..e1881ea7 100644 --- a/content/en/docs/tutorials/dashboard-branding.md +++ b/content/en/docs/tutorials/dashboard-branding.md @@ -62,7 +62,7 @@ Footer has a dedicated component which can be found in [`footer.js`](https://git ## Text changes -Every text in this application is coming from a translation file located in [`langauges.json`](https://github.com/plgd-dev/hub/tree/main/http-gateway/web/src/languages/langauges.json). This object contains a language block for each language you support in your application. If a block is missing you can duplicate an existing block and modify the block with the language code that is missing. +Every text in this application is coming from a translation file located in [`languages.json`](https://github.com/plgd-dev/hub/blob/main/http-gateway/web/src/languages/languages.json). This object contains a language block for each language you support in your application. If a block is missing you can duplicate an existing block and modify the block with the language code that is missing. Some messages might be missing. This is due to fact that they were not yet translated. You can add them manually or use a language editor like [POEditor](https://poeditor.com/). diff --git a/layouts/index.html b/layouts/index.html index f2b03e69..b54b3d70 100644 --- a/layouts/index.html +++ b/layouts/index.html @@ -1 +1,20 @@ -{{ with .GetPage "docs/" }}{{ .Render }}{{ end }} \ No newline at end of file + + + + + + {{ .Title }} + + + + + +
+ + {{ with .GetPage "docs/" }}{{ .Render }}{{ end }} +
+
+ +
+ + diff --git a/scripts/push-to-algolia.js b/scripts/push-to-algolia.js new file mode 100644 index 00000000..849106c7 --- /dev/null +++ b/scripts/push-to-algolia.js @@ -0,0 +1,32 @@ +const algoliasearch = require('algoliasearch'); +const fs = require('fs'); + +// Initialize Algolia client +const client = algoliasearch(process.env.APPLICATION_ID, process.env.API_KEY); +const index = client.initIndex('doc'); + + +process.argv.forEach((val, index) => { + console.log(`args ${index}: ${val}`); +}); + +// Read JSON file +const jsonData = fs.readFileSync(process.argv[2], 'utf8'); + +// Parse JSON data +const records = JSON.parse(jsonData); + +// Clear the existing index +index.clearObjects() + .then(() => { + console.log('Existing records cleared'); + // Add or update records in Algolia index + return index.saveObjects(records, { autoGenerateObjectIDIfNotExist: true }); + }) + .then(({ objectIDs }) => { + console.log('Records added/updated:', objectIDs); + }) + .catch(error => { + console.error('Error adding/updating records:', error); + }); + diff --git a/themes/plgd b/themes/plgd index 6ea8a18b..eb3f6a64 160000 --- a/themes/plgd +++ b/themes/plgd @@ -1 +1 @@ -Subproject commit 6ea8a18bf51dca9e871d7f04f3a63926bb5df677 +Subproject commit eb3f6a64f1876c9184f587c6719feb5aeca88ab6 diff --git a/tools/adjust-algolia-output/algolia.json b/tools/adjust-algolia-output/algolia.json new file mode 100644 index 00000000..feba1370 --- /dev/null +++ b/tools/adjust-algolia-output/algolia.json @@ -0,0 +1,1717 @@ +[ + { + "title": "Docs", + "uri": "en/docs", + "content": "", + "objectID": "en/docs", + "titlePage": "What can we help with?", + "description": "Welcome to plgd knowledge base! Search our extensive documentation and self-help resources.", + "searchPlaceHolder": "I am searching for...", + "getStartedTitle": "Get started", + "readLinkTitle": "Read more", + "otherTopicsTitle": "Other topics", + "recentlyUpdatedTitle": "Recently updated", + "needHelpTitle": "Need help?", + "contactUsButtonText": "Contact us" + }, + { + "title": "Architecture", + "uri": "en/docs/architecture", + "content": "", + "objectID": "en/docs/architecture", + "weight": 3 + }, + { + "title": "Component Overview", + "uri": "en/docs/architecture/component-overview", + "content": "CoAP Gateway CoAP gateway acts CoAP Client communicating IoT devices serve CoAP Servers following OCF specification component diagram describes responsibilities gateway are Handle maintain TCP connections coming devices Authenticate authorize requests see 5 5 5 device conjunction OAuth2 0 Server Process device CRUDN operations nature forwarded Resource Aggregate Resource Directory Operational flow device becomes operational able interact devices needs appropriately onboarded first step onboarding device configure ownership see 5 3 3 legitimate user owns purchases device uses one Owner Transfer Methods OTMs within Onboarding tool establish ownership Once ownership established OBT provisions device see 5 3 4 device provisioned plgd hub see 8 1 2 3 successful provisioning device establish TLS connection see 7 2 using certificate based credentials Use plgd Client Application easy device discovery ownership configuration provisioning plgd hub Device Onboarding startuml Sequence skinparam backgroundColor grey hide footbox participant D Device participant CGW CoAP Gateway participant Identity Store participant OBT Onboarding Tool OBT Discover devices D OBT group OCF Onboarding OBT D Establish Device Owner return Ownership established OBT D Provisioning security configuration return Provisioning successful end group OCF Cloud Provisioning OBT D Provisioning cloud configuration resource return Provisioning successful end D CGW Establish TCP connection enduml TCP connection device established CoAP Gateway authenticated not authorized order device reachable TCP connection authorized flow describes operation new device within first connection device Sign register plgd hub see 8 1 4 authorization code received during OCF Cloud Provisioning process described diagram above exchanged CoAP Gateway access refresh token returned device process described detail OCF Cloud Security Specification see 6 2 Hub Registration startuml Sequence skinparam backgroundColor grey hide footbox participant D Device participant CGW CoAP Gateway participant O OAuth 2 0 Server participant Identity Store D CGW Sign group OAuth2 0 Authorization Code Grant Flow CGW O Verify exchange authorization code JWT access token return Ok n JWT Access Token Refresh Token end CGW Register assign device user return Registered return Signed up n JWT Access Token Refresh Token enduml Successful registration plgd dev followed authorization request called Sign In Sign required right successfully established TCP connection CoAP Gateway otherwise device won t reachable marked online device requests blocked unless device successfully Signs In Successful authorization precedes validation JWT Access Token JWT access tokens supported device Device Authorization startuml Sequence skinparam backgroundColor grey hide footbox participant D Device participant CGW CoAP Gateway participant Identity Store participant EB Event Bus participant RA Resource Aggregate D CGW Sign CGW CGW Validate JWT Access Token CGW device registered return Ok CGW EB Subscribe device owner events CGW RA Declare device online return return Signed enduml Device capabilities represented form resources Configuration terms whether resource published remotely accessible plgd hub not handled IoTivity Lite API Whether resource published device vendor want resources accessible proximity network Resource information published plgd hub provides insights device capabilities Clients interested not resource href location request resource representation mainly resource type allows filter capabilities able control example client application controls lighting will search Resource Directory lights user home filtering resources resource type oic r switch binary resources data temperature moisture etc not interest application doesn t understand representation Information published doesn t contain resource representation resource information described see 6 1 3 2 2 di e61c3e6b 9c54 4b81 8ce5 f9039c1d04d9 links anchor ocf e61c3e6b 9c54 4b81 8ce5 f9039c1d04d9 href myLightSwitch rt oic r switch binary if oic if a oic if baseline p bm 3 eps ep coaps fe80 b1d6 1111 pri 2 ep coaps fe80 b1d6 1122 ttl 600476 resource publish request forwarded Resource Aggregate registers new resource process makes resource discoverable plgd hub starts observation every successfully published resource sending OBSERVE request received notifications device sent Resource Aggregate record change response resource observation request contains actual representation CoAP Gateway doesn t pull data all Additional responses called notifications sent device whenever representation device changes want know Device Twin it s state changes please go Device Twin section Resource Publish Subscri", + "objectID": "en/docs/architecture/component-overview", + "description": "L3 and L4 plgd overview", + "date": "2021-05-13", + "categories": [ + "architecture", + "C4 model", + "components" + ], + "keywords": [ + "c4 model", + "diagrams" + ], + "weight": 4 + }, + { + "title": "Domain Overview", + "uri": "en/docs/architecture/introduction", + "content": "Internet Things IoT network physical devices embedded electronics software sensors actuators connectivity purpose enabling things connect exchange data Thus creating opportunities direct integration physical world computer based systems resulting efficiency improvements economic benefits reduced human intervention Wikipedia Internet Things IoT device senses change representing world around it developer determines world represented device processed application specific domain Technology support transfer data standardized secured way IoT platform not limit nor set boundaries limit evolution system menu id file value File popup menuitem value New onclick CreateNewDoc value Open onclick OpenDoc value Close onclick CloseDoc Domain sphere knowledge influence activity IoT itself likely not domain business group technology achievements last decades 20th century opening doors new possibilities business domain IoT facilitates modelling external world specific needs form resources events transferred secure traceable manner application located off premise even on premise goal developers focus primarily domain business Architectural Drivers Technical Contraints CoAP OCF mandates CoAP support compliant devices CoAP TCP UDP may preferred messaging local networks chattiness highly detrimental due power bandwidth constraints CoAP TCP preferred situations device communicating remote server due greater QoS guarantees TCP substantially better support UDP cloud native use cases TLS responsible security data integrity new component connecting device CBOR Default media type used communication OCF compliant devices components CBOR format supported default Quality Attributes Scalable Ericsson forecast will around 18 billion IoT devices online 2022 system needs able not handle large scale connectivity load rapidly scale down response load High Availability IoT devices often crucial safety performance system they re used in devices may inherently low QoS environments responsibility hub always available when devices need it otherwise not weakest link Traceable users devices transceiving data time result types errors negatively impacting business operations beneficial track activities within system effective error solving future prediction based recognised patterns Cost Efficient future users won t knowledge infrastructure operations whole system not own data center hosting solution increases importance ease use cost efficiency cloud providers offer similar set services functional point view solution able advantage services save money alleviating burden missing know how increasing runtime optimizations Multitenant Solution providers multiple customers ability use one instance system customers secured way important client able access devices it s authorized access Domain Decomposition Resources Bounded Context Servers IoT Devices OCF enabled represented form resources similar REST Resources hosted server IoT Device connected plgd hub able publish resources accessible remotely decentralized component means plgd hub works gateway resource directory connected authorized servers clients understand resource is read chapter 7 Resource model Connected server client can Publish Unpublish resources resource represented URI properties resource types interfaces Browse Resources Browse resources published servers Resource Directory Retrieve Resource Resource Bounded context keeps up to date representation remote resource Update resource representation Resource Bounded context propagates update device s resource Observe Resource change resource creates event client device subscribed Identities Bounded Context authorized client application interested data connected plgd hub IoT Device able perform action device access device s data means authorized client server able browse CRUDN resource published Resource Directory server client required successfully sign up sign in right connecting plgd hub During sign up process thought registration one time use authorization code exchange access token uniquely represents server client Returned access token used sign in request server client signed in requests not forwarded plgd system connected server client belongs user requested authorization code Connected server client can Sign up Registration plgd hub valid authorization code Sign in Authorize connection provided access token Sign out", + "objectID": "en/docs/architecture/introduction", + "description": "plgd domain overview", + "date": "2021-05-13", + "categories": [ + "architecture" + ], + "keywords": [ + "domain" + ], + "weight": 1 + }, + { + "title": "System Overview", + "uri": "en/docs/architecture/system-overview", + "content": "System Context Diagram plgd Context Diagram", + "objectID": "en/docs/architecture/system-overview", + "description": "L1 and L2 plgd overview", + "date": "2021-05-13", + "categories": [ + "architecture", + "C4 model" + ], + "keywords": [ + "c4 model", + "diagrams" + ], + "weight": 3 + }, + { + "title": "Configuration", + "uri": "en/docs/configuration", + "content": "", + "objectID": "en/docs/configuration", + "weight": 9 + }, + { + "title": "Certificate Authority", + "uri": "en/docs/configuration/certificate-authority", + "content": "service used sign identity certificates devices plgd dev device client Initialization SDK requires Identity Certificate issued service successful user authorization SDK able discover configure ownership described here During process CSR Certificate Signing Request sent Certificate Authority returns device s Identity Certificate Docker Image docker pull ghcr io plgd dev hub certificate authority latest YAML Configuration configuration template available certificate authority config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano gRPC API gRPC API Certificate Authority service defined here Property Type Description Default apis grpc address string Listen specification grpc client connection 0 0 0 0 9100 apis grpc enforcementPolicy minTime string minimum amount time client wait sending keepalive ping Otherwise server close connection 5s apis grpc enforcementPolicy permitWithoutStream bool true server allows keepalive pings even when no active streams RPCs Otherwise server close connection true apis grpc keepAlive maxConnectionIdle string duration amount time idle connection closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAge string duration maximum amount time connection may exist will closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAgeGrace string additive period MaxConnectionAge connection will forcibly closed 0s means infinity 0s apis grpc keepAlive time string duration time server doesn t activity pings client transport alive 2h apis grpc keepAlive timeout string having pinged keepalive check client waits duration Timeout no activity seen even connection closed 20s apis grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc tls keyFile string File path private key PEM format apis grpc tls certFile string File path certificate PEM format apis grpc tls clientCertificateRequired bool true require client certificate true apis grpc authorization ownerClaim string Claim used identify owner device sub apis grpc authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis grpc authorization audience string Identifier API configured OAuth provider apis grpc authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis grpc authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis grpc authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis grpc authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis grpc authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis grpc authorization http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc authorization http tls keyFile string File path private key PEM format apis grpc authorization http tls certFile string File path certificate PEM format apis grpc authorization http tls useSystemCAPool bool true use system certification pool false HTTP API HTTP Certificate Authority APIs defined swagger configuration apis http tls apis http authorization inherited gRPC API Property Type Description Default apis http address string Listen specification http client connection 0 0 0 0 9101 apis http readTimeout string maximum duration reading entire request including body server zero negative value means will no timeout 8s apis http readHeaderTimeout string amount time allowed read request headers server readHeaderTimeout zero value readTimeout used zero no timeout 4s apis http writeTimeout string maximum duration server times writing response zero negative value means will no timeout 16s apis http idleTimeout string maxim", + "objectID": "en/docs/configuration/certificate-authority", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 7 + }, + { + "title": "Cloud2Cloud Connector", + "uri": "en/docs/configuration/cloud2cloud-connector", + "content": "C2C Connector connects hub implementing Open Connectivity Foundation s Cloud API Cloud Services mirror devices linked instance yours Docker Image docker pull ghcr io plgd dev hub cloud2cloud connector latest YAML Configuration configuration template available cloud2cloud connector config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano HTTP API Property Type Description Default apis http address string Listen specification http client connection 0 0 0 0 9100 apis http readTimeout string maximum duration reading entire request including body server zero negative value means will no timeout 8s apis http readHeaderTimeout string amount time allowed read request headers server readHeaderTimeout zero value readTimeout used zero no timeout 4s apis http writeTimeout string maximum duration server times writing response zero negative value means will no timeout 16s apis http idleTimeout string maximum amount time server waits next request when keep alives enabled idleTimeout zero value readTimeout used zero no timeout 30s apis http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis http tls keyFile string File path private key PEM format apis http tls certFile string File path certificate PEM format apis http tls clientCertificateRequired bool true require client certificate true apis http eventsURL string External url events hub will send apis http pullDevices disabled bool Disable devices via pull clouds true apis http pullDevices interval string Time interval pulls 5s apis http clientID string Client ID exchange authorization code access token apis http clientSecretFile string File path client secret required exchange authorization code access token apis http scopes string array List required scopes apis http authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis http authorization audience string Identifier API configured OAuth provider apis http authorization ownerClaim string Claim used identify owner device sub apis http authorization redirectURL string External redirect url acquire authorization code apis http authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis http authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis http authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis http authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis http authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis http authorization http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis http authorization http tls keyFile string File path private key PEM format apis http authorization http tls certFile string File path certificate PEM format apis http authorization http tls useSystemCAPool bool true use system certification pool false one client multiple APIs OAuth system want prevent able contact APIs system one token audience allows request token specific API configure myplgdc2c api Auth0 set want validate it Identity Store Client Client configurations internally connect Identity Store service Property Type Description Default clients identityStore grpc address string Identity Store service address 127 0 0 1 9100 clients identityStore grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates clients identityStore grpc tls keyFile string File path private key PEM format clients identityStore grpc tls certFile string File path certificate PEM format clients identityStore grpc tls useSystem", + "objectID": "en/docs/configuration/cloud2cloud-connector", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 9 + }, + { + "title": "Cloud2Cloud Gateway", + "uri": "en/docs/configuration/cloud2cloud-gateway", + "content": "C2C Gateway implements Open Connectivity Foundation s Cloud API Cloud Services providing API s mirror user s devices different OCF standardized hub Docker Image docker pull ghcr io plgd dev hub cloud2cloud gateway latest YAML Configuration configuration template available cloud2cloud gateway config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano HTTP API Property Type Description Default apis http address string Listen specification http client connection 0 0 0 0 9100 apis http readTimeout string maximum duration reading entire request including body server zero negative value means will no timeout 8s apis http readHeaderTimeout string amount time allowed read request headers server readHeaderTimeout zero value readTimeout used zero no timeout 4s apis http writeTimeout string maximum duration server times writing response zero negative value means will no timeout 16s apis http idleTimeout string maximum amount time server waits next request when keep alives enabled idleTimeout zero value readTimeout used zero no timeout 30s apis http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis http tls keyFile string File path private key PEM format apis http tls certFile string File path certificate PEM format apis http tls clientCertificateRequired bool true require client certificate true apis http authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis http authorization audience string Identifier API configured OAuth provider apis http authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis http authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis http authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis http authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis http authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis http authorization http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis http authorization http tls keyFile string File path private key PEM format apis http authorization http tls certFile string File path certificate PEM format apis http authorization http tls useSystemCAPool bool true use system certification pool false Event Bus plgd hub uses NATS messaging system event bus Property Type Description Default clients eventBus nats url string URL nats messaging system nats localhost 4222 clients eventBus nats pendingLimits msgLimit int Limit number messages queue 1 means unlimited 524288 clients eventBus nats pendingLimits bytesLimit int Limit buffer size queue 1 means unlimited 67108864 clients eventBus nats tls caPool string File paths root certificates PEM format file may contain multiple certificates clients eventBus nats tls keyFile string File name private key PEM format clients eventBus nats tls certFile string File name certificate PEM format clients eventBus nats tls useSystemCAPool bool true use system certification pool false GRPC Gateway Client Client configurations internally connect GRPC Gateway service Property Type Description Default clients grpcGateway grpc address string GRPC Gateway service address 127 0 0 1 9100 clients grpcGateway grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates clients grpcGateway grpc tls keyFile string File path private key PEM format clients grpcGateway grpc tls certFile string File path certificate PEM format clients grpcGateway grpc tls useSystemCAPool bool true", + "objectID": "en/docs/configuration/cloud2cloud-gateway", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 8 + }, + { + "title": "CoAP Gateway", + "uri": "en/docs/configuration/coap-gateway", + "content": "CoAP Gateway provides API devices clients following Open Connectivity Foundation specification Docker Image docker pull ghcr io plgd dev hub coap gateway latest YAML Configuration configuration template available coap gateway config yaml Logging Property Type Description Default log dumpBody bool Set true dump raw messages false log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano CoAP API CoAP API specified Open Connectivity Foundation Device Cloud Services Property Type Description Default apis coap address string Listen specification coap client connection 0 0 0 0 5684 apis coap protocols string Protocol coap connection supported values are tcp udp tcp apis coap externalAddress string External address including public domain IP coap client connection coap gw example com 5684 apis coap maxMessageSize int Max message size sent received via coap i e 256 1024 262144 bytes 262144 apis coap ownerCacheExpiration string Time limit long keep subscribed device updates last use given cache item 1m apis coap subscriptionBufferSize int maximum buffer size one events subscription 1000 apis coap messagePoolSize int Defines maximum preallocated messages pool parse create coap messages 1000 apis coap keepAlive timeout string Time limit close inactive connection 20s apis coap blockwiseTransfer enabled bool true enable blockwise transfer coap messages true apis coap blockwiseTransfer blockSize int Size blockwise transfer block 1024 apis coap tls enabled bool true require server certificate ssl connection true apis coap tls disconnectOnExpiredCertificate bool true device expired certificates will disconnected false apis coap tls caPool string File paths root certificates PEM format file may contain multiple certificates apis coap tls keyFile string File path private key PEM format apis coap tls certFile string File path certificate PEM format apis coap tls clientCertificateRequired bool true require client certificate true apis coap tls identityPropertiesRequired bool true require EKU 1 3 6 1 4 1 44924 1 6 CN uuid client certificate defined OCF true OAuth2 0 Client OAuth2 0 Client used issuing authorization code used Onboarding Tool during device provisioning exchanged access token during SignUp operation Property Type Description Default apis coap authorization ownerClaim string Claim used identify owner device Combination ownerClaim set sub not compatible least one authorization provider uses grant type clientCredentials sub apis coap authorization deviceIDClaim string Claim used identify device id device Empty means JWT doesn t contain it apis coap authorization providers name string Provider name register request device contain one names providers apis coap authorization providers clientID string Client ID exchange authorization code access token apis coap authorization providers clientSecretFile string File path client secret required exchange authorization code access token apis coap authorization providers grantType string grant type OAuth provider specifies device signing process authorized Combination apis coap authorization ownerClaim set sub not compatible least one authorization provider uses grant type clientCredentials Supported values authorizationCode clientCredentials authorizationCode apis coap authorization providers scopes string array List required scopes apis coap authorization providers authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis coap authorization providers audience string Audience OAuth provider apis coap authorization providers redirectURL string Redirect url used obtain device access token apis coap authorization providers http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis coap authorization providers http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis coap authorization providers http maxIdleConnsPerHost int non zero controls maximum idle ke", + "objectID": "en/docs/configuration/coap-gateway", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 1 + }, + { + "title": "Device Provisioning Service", + "uri": "en/docs/configuration/device-provisioning-service", + "content": "Device Provisioning Service provides API provision device plgd hub Docker Image use image need setup K8s access private registry docker pull ghcr io plgd dev device provisioning service device provisioning service latest YAML Configuration configuration template available config yaml Logging Property Type Description Default log dumpBody bool Set true dump raw messages false log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano CoAP API CoAP API specified workflow Property Type Description Default apis coap address string Listen specification coap client connection 0 0 0 0 5688 apis coap protocols string Protocol coap connection supported values are tcp udp tcp apis coap maxMessageSize int Max message size sent received via coap i e 256 1024 262144 bytes 262144 apis coap messagePoolSize int Defines maximum preallocated messages pool parse create coap messages 1000 apis coap inactivityMonitor timeout string Time limit close inactive connection 20s apis coap blockwiseTransfer enabled bool true enable blockwise transfer coap messages true apis coap blockwiseTransfer blockSize int Size blockwise transfer block 1024 apis coap tls keyFile string File path private key PEM format apis coap tls certFile string File path certificate PEM format HTTP API plgd device provisioning service REST API defined swagger Property Type Description Default apis http enabled bool Enable HTTP API false apis http address string Listen specification http client connection 0 0 0 0 9100 apis http tls caPool string File path root certificate PEM format contain multiple certificates single file apis http tls keyFile string File path private key PEM format apis http tls certFile string File path certificate PEM format apis http tls clientCertificateRequired bool true require client certificate true apis http authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis http authorization audience string Identifier API configured OAuth provider apis http authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis http authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis http authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis http authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis http authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis http authorization http tls caPool string File path root certificate PEM format contain multiple certificates single file apis http authorization http tls keyFile string File path private key PEM format apis http authorization http tls certFile string File path certificate PEM format apis http authorization http tls useSystemCAPool bool true use system certification pool false apis http readTimeout string maximum duration reading entire request including body server zero negative value means will no timeout 8s apis http readHeaderTimeout string amount time allowed read request headers server readHeaderTimeout zero value readTimeout used zero no timeout 4s apis http writeTimeout string maximum duration server times writing response zero negative value means will no timeout 16s apis http idleTimeout string maximum amount time server waits next request when keep alives enabled idleTimeout zero value readTimeout used zero no timeout 30s Open telemetry exporter plgd open telemetry exporter configuration Property Type Description Default clients openTelemetryCollector grpc enabled bool Enable OTLP gRPC exporter false clients openTelemetryCollector grpc address string gRPC collector exporter going send data clients openTeleme", + "objectID": "en/docs/configuration/device-provisioning-service", + "description": "Device Provisioning Service configuration overview", + "date": "2023-05-18", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 9 + }, + { + "title": "gRPC Gateway", + "uri": "en/docs/configuration/grpc-gateway", + "content": "gRPC Gateway exposes client s gRPC API manage user s devices Docker Image docker pull ghcr io plgd dev hub grpc gateway latest YAML Configuration configuration template available grpc gateway config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano gRPC API gRPC API gRPC Gateway service defined here Property Type Description Default apis grpc address string Listen specification grpc client connection 0 0 0 0 9100 apis grpc ownerCacheExpiration string Time limit long keep subscribed device updates last use given cache item 1m apis grpc subscriptionBufferSize int maximum buffer size one events subscription 1000 apis grpc enforcementPolicy minTime string minimum amount time client wait sending keepalive ping Otherwise server close connection 5s apis grpc enforcementPolicy permitWithoutStream bool true server allows keepalive pings even when no active streams RPCs Otherwise server close connection true apis grpc keepAlive maxConnectionIdle string duration amount time idle connection closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAge string duration maximum amount time connection may exist will closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAgeGrace string additive period MaxConnectionAge connection will forcibly closed 0s means infinity 0s apis grpc keepAlive time string duration time server doesn t activity pings client transport alive 2h apis grpc keepAlive timeout string having pinged keepalive check client waits duration Timeout no activity seen even connection closed 20s apis grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc tls keyFile string File path private key PEM format apis grpc tls certFile string File path certificate PEM format apis grpc tls clientCertificateRequired bool true require client certificate true apis grpc authorization ownerClaim string Claim used identify owner device sub apis grpc authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis grpc authorization audience string Identifier API configured OAuth provider apis grpc authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis grpc authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis grpc authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis grpc authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis grpc authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis grpc authorization http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc authorization http tls keyFile string File path private key PEM format apis grpc authorization http tls certFile string File path certificate PEM format apis grpc authorization http tls useSystemCAPool bool true use system certification pool false Identity Store Client Client configurations internally connect Identity Store service Property Type Description Default clients identityStore grpc address string Identity Store service address 127 0 0 1 9100 clients identityStore grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates clients identityStore grpc tls keyFile string File path private key PEM format clients identityStore grpc tls certFile string File path certificate PEM format clients identityStore grpc tls useSystemCAPool bool true use system certification pool false clients identityStore grpc keepAlive time string duration time client doesn t activity pings server transport alive 10s clients identityStore grpc keepAlive tim", + "objectID": "en/docs/configuration/grpc-gateway", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 3 + }, + { + "title": "HTTP Gateway", + "uri": "en/docs/configuration/http-gateway", + "content": "HTTP Gateway exposes client s REST API manage user s devices Web UI known plgd Dashboard Docker Image docker pull ghcr io plgd dev hub http gateway latest YAML Configuration configuration template available http gateway config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano HTTP API APIs HTTP Gateway service defined uri swagger REST API Property Type Description Default apis http address string Listen specification http client connection 0 0 0 0 9100 apis http readTimeout string maximum duration reading entire request including body server zero negative value means will no timeout 8s apis http readHeaderTimeout string amount time allowed read request headers server readHeaderTimeout zero value readTimeout used zero no timeout 4s apis http writeTimeout string maximum duration server times writing response zero negative value means will no timeout 16s apis http idleTimeout string maximum amount time server waits next request when keep alives enabled idleTimeout zero value readTimeout used zero no timeout 30s apis http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis http tls keyFile string File path private key PEM format apis http tls certFile string File path certificate PEM format apis http tls clientCertificateRequired bool true require client certificate true apis http websocket streamBodyLimit int Limit size buffer used reading grpc stream 262144 apis http websocket pingFrequency string Ping frequency specifies ping interval pings 10s apis http authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis http authorization audience string Identifier API configured OAuth provider apis http authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis http authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis http authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis http authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis http authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis http authorization http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis http authorization http tls keyFile string File path private key PEM format apis http authorization http tls certFile string File path certificate PEM format apis http authorization http tls useSystemCAPool bool true use system certification pool false GRPC Gateway Client Client configurations internally connect GRPC Gateway service Property Type Description Default clients grpcGateway grpc address string GRPC Gateway service address 127 0 0 1 9100 clients grpcGateway grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates clients grpcGateway grpc tls keyFile string File path private key PEM format clients grpcGateway grpc tls certFile string File path certificate PEM format clients grpcGateway grpc tls useSystemCAPool bool true use system certification pool false clients grpcGateway grpc keepAlive time string duration time client doesn t activity pings server transport alive 10s clients grpcGateway grpc keepAlive timeout string having pinged keepalive check client waits duration Timeout no activity seen even connection closed 20s clients grpcGateway grpc keepAlive permitWithoutStream bool true client sends keepalive pings even no active RPCs false when no active RPCs Time Timeout will ignored no keepalive pings will sent false Web UI configurations plgd Dashboard described here Property Type Description Default ", + "objectID": "en/docs/configuration/http-gateway", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 2 + }, + { + "title": "Identity Store", + "uri": "en/docs/configuration/identity-store", + "content": "Identity Store manages devices owners Docker Image docker pull ghcr io plgd dev hub identity store latest YAML Configuration configuration template available identity store config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano gRPC API gRPC API Identity Store service defined here Property Type Description Default apis grpc address string Listen specification grpc client connection 0 0 0 0 9100 apis grpc enforcementPolicy minTime string minimum amount time client wait sending keepalive ping Otherwise server close connection 5s apis grpc enforcementPolicy permitWithoutStream bool true server allows keepalive pings even when no active streams RPCs Otherwise server close connection true apis grpc keepAlive maxConnectionIdle string duration amount time idle connection closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAge string duration maximum amount time connection may exist will closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAgeGrace string additive period MaxConnectionAge connection will forcibly closed 0s means infinity 0s apis grpc keepAlive time string duration time server doesn t activity pings client transport alive 2h apis grpc keepAlive timeout string having pinged keepalive check client waits duration Timeout no activity seen even connection closed 20s apis grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc tls keyFile string File path private key PEM format apis grpc tls certFile string File path certificate PEM format apis grpc tls clientCertificateRequired bool true require client certificate true apis grpc authorization ownerClaim string Claim used identify owner device sub apis grpc authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis grpc authorization audience string Identifier API configured OAuth provider apis grpc authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis grpc authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis grpc authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis grpc authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis grpc authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis grpc authorization http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc authorization http tls keyFile string File path private key PEM format apis grpc authorization http tls certFile string File path certificate PEM format apis grpc authorization http tls useSystemCAPool bool true use system certification pool false Event Bus plgd hub uses NATS messaging system event bus Property Type Description Default clients eventBus nats url string URL nats messaging system nats localhost 4222 clients eventBus nats flusherTimeout string Define flush timeout publishing message 30s clients eventBus nats jetstream bool true events will published jetstream false clients eventBus nats tls caPool string File paths root certificates PEM format file may contain multiple certificates clients eventBus nats tls keyFile string File name private key PEM format clients eventBus nats tls certFile string File name certificate PEM format clients eventBus nats tls useSystemCAPool bool true use system certification pool false Storage plgd hub uses MongoDB database owner s device store Property Type Description Default clients storage mongoDB uri string URI mongo database mongodb localhost 27017 clients storage mongoDB ", + "objectID": "en/docs/configuration/identity-store", + "description": "Service configuration overview", + "date": "2021-10-04", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 6 + }, + { + "title": "[MOCK] OAuth Server", + "uri": "en/docs/configuration/oauth-server", + "content": "OAuth2 0 Mock Server used automated tests bundle container optionally deployment using HELM chart development purposes Docker Image docker pull ghcr io plgd dev hub mock oauth server latest YAML Configuration configuration template available test oauth server config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano HTTP API HTTP API OAuth Server service defined Property Type Description Default apis http address string Listen specification http client connection 0 0 0 0 9100 apis http readTimeout string maximum duration reading entire request including body server zero negative value means will no timeout 8s apis http readHeaderTimeout string amount time allowed read request headers server readHeaderTimeout zero value readTimeout used zero no timeout 4s apis http writeTimeout string maximum duration server times writing response zero negative value means will no timeout 16s apis http idleTimeout string maximum amount time server waits next request when keep alives enabled idleTimeout zero value readTimeout used zero no timeout 30s apis http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis http tls keyFile string File path private key PEM format apis http tls certFile string File path certificate PEM format apis http tls clientCertificateRequired bool true require client certificate true OAuth Signer Signer configuration issue ID access tokens OAuth provider mock testing Property Type Description Default oauthSigner idTokenKeyFile string File path private RSA key PEM format required ID token signing oauthSigner accessTokenKeyFile string File path private ECDSA key PEM format required access token signing oauthSigner domain string Domain address OAuth APIs oauthSigner clients 0 id string client id used oauth clients test oauthSigner clients 0 authorizationCodeLifetime string validity generated authorization code 10m0s oauthSigner clients 0 accessTokenLifetime string validity generated access token lifetime 0s means forever 0s oauthSigner clients 0 codeRestrictionLifetime string define period long cannot used again authorization code exchange first use 0s Note string type related time i e timeout idleConnTimeout expirationTime decimal numbers optional fraction unit suffix 300ms 1 5h 2h45m Valid time units ns us ms s m h", + "objectID": "en/docs/configuration/oauth-server", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 10 + }, + { + "title": "Resource Aggregate", + "uri": "en/docs/configuration/resource-aggregate", + "content": "Resource Aggregate translates commands events stores database publishes messaging system Docker Image docker pull ghcr io plgd dev hub resource aggregate latest YAML Configuration configuration template available resource aggregate config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano gRPC API gRPC API Resource Aggregate service defined here Property Type Description Default apis grpc ownerCacheExpiration string Time limit long keep subscribed device updates last use given cache item 1m apis grpc address string Listen specification grpc client connection 0 0 0 0 9100 apis grpc enforcementPolicy minTime string minimum amount time client wait sending keepalive ping Otherwise server close connection 5s apis grpc enforcementPolicy permitWithoutStream bool true server allows keepalive pings even when no active streams RPCs Otherwise server close connection true apis grpc keepAlive maxConnectionIdle string duration amount time idle connection closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAge string duration maximum amount time connection may exist will closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAgeGrace string additive period MaxConnectionAge connection will forcibly closed 0s means infinity 0s apis grpc keepAlive time string duration time server doesn t activity pings client transport alive 2h apis grpc keepAlive timeout string having pinged keepalive check client waits duration Timeout no activity seen even connection closed 20s apis grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc tls keyFile string File path private key PEM format apis grpc tls certFile string File path certificate PEM format apis grpc tls clientCertificateRequired bool true require client certificate true apis grpc authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis grpc authorization audience string Identifier API configured OAuth provider apis grpc authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis grpc authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis grpc authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis grpc authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis grpc authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis grpc authorization http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc authorization http tls keyFile string File path private key PEM format apis grpc authorization http tls certFile string File path certificate PEM format apis grpc authorization http tls useSystemCAPool bool true use system certification pool false Event Bus plgd hub uses NATS messaging system event bus Property Type Description Default clients eventBus nats url string URL nats messaging system nats localhost 4222 clients eventBus nats flusherTimeout string Define flush timeout publishing message 30s clients eventBus nats jetstream bool true events will published jetstream false clients eventBus nats tls caPool string File paths root certificates PEM format file may contain multiple certificates clients eventBus nats tls keyFile string File name private key PEM format clients eventBus nats tls certFile string File name certificate PEM format clients eventBus nats tls useSystemCAPool bool true use system certification pool false Event Store plgd hub uses MongoDB database event store Property Type Description Default clients eventStore defaul", + "objectID": "en/docs/configuration/resource-aggregate", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 4 + }, + { + "title": "Resource Directory", + "uri": "en/docs/configuration/resource-directory", + "content": "Resource Directory maintains projection devices requested clients plgd gateways Docker Image docker pull ghcr io plgd dev hub resource directory latest YAML Configuration configuration template available resource directory config yaml Logging Property Type Description Default log level string Logging enabled level info log encoding string Logging format supported values are json console json log stacktrace enabled bool Log stacktrace false log stacktrace level string Stacktrace level warn log encoderConfig timeEncoder string Time format logs supported values are rfc3339nano rfc3339 rfc3339nano gRPC API gRPC API Resource Directory service Property Type Description Default apis grpc address string Listen specification grpc client connection 0 0 0 0 9100 apis grpc ownerCacheExpiration string Time limit long keep subscribed device updates last use given cache item 1m apis grpc enforcementPolicy minTime string minimum amount time client wait sending keepalive ping Otherwise server close connection 5s apis grpc enforcementPolicy permitWithoutStream bool true server allows keepalive pings even when no active streams RPCs Otherwise server close connection true apis grpc keepAlive maxConnectionIdle string duration amount time idle connection closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAge string duration maximum amount time connection may exist will closed sending GoAway 0s means infinity 0s apis grpc keepAlive maxConnectionAgeGrace string additive period MaxConnectionAge connection will forcibly closed 0s means infinity 0s apis grpc keepAlive time string duration time server doesn t activity pings client transport alive 2h apis grpc keepAlive timeout string having pinged keepalive check client waits duration Timeout no activity seen even connection closed 20s apis grpc tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc tls keyFile string File path private key PEM format apis grpc tls certFile string File path certificate PEM format apis grpc tls clientCertificateRequired bool true require client certificate true apis grpc authorization ownerClaim string Claim used identify owner device sub apis grpc authorization authority string Authority address token issuing authentication server Services will use URI find retrieve public key used validate token s signature apis grpc authorization audience string Identifier API configured OAuth provider apis grpc authorization http maxIdleConns int controls maximum number idle keep alive connections across hosts Zero means no limit 16 apis grpc authorization http maxConnsPerHost int optionally limits total number connections per host including connections dialing active idle states limit violation dials will block Zero means no limit 32 apis grpc authorization http maxIdleConnsPerHost int non zero controls maximum idle keep alive connections keep per host zero DefaultMaxIdleConnsPerHost used 16 apis grpc authorization http idleConnTimeout string maximum amount time idle keep alive connection will remain idle closing itself Zero means no limit 30s apis grpc authorization http timeout string time limit requests made Client Timeout zero means no timeout 10s apis grpc authorization http tls caPool string File paths root certificates PEM format file may contain multiple certificates apis grpc authorization http tls keyFile string File path private key PEM format apis grpc authorization http tls certFile string File path certificate PEM format apis grpc authorization http tls useSystemCAPool bool true use system certification pool false Event Bus plgd hub uses NATS messaging system event bus Property Type Description Default clients eventBus goPoolSize int Number routines process events projection 16 clients eventBus nats url string URL nats messaging system nats localhost 4222 clients eventBus nats pendingLimits msgLimit int Limit number messages queue 1 means unlimited 524288 clients eventBus nats pendingLimits bytesLimit int Limit buffer size queue 1 means unlimited 67108864 clients eventBus nats tls caPool string File paths root certificates PEM format file may contain multiple certificates clients eventBus nats tls keyFile string File name private key PEM format clients eventBus nats tls certFile string File name certificate PEM format clients eventBus nats tls useSystemCAPool bool true use system certification poo", + "objectID": "en/docs/configuration/resource-directory", + "description": "Service configuration overview", + "date": "2021-10-01", + "categories": [ + "configuration", + "deployment" + ], + "keywords": [ + "configuration" + ], + "weight": 5 + }, + { + "title": "Deployment to K8S", + "uri": "en/docs/deployment", + "content": "", + "objectID": "en/docs/deployment", + "weight": 5 + }, + { + "title": "Deployment", + "uri": "en/docs/deployment/deployment", + "content": "section find several examples deploy plgd hub external OAuth2 0 Server mocked one development purposes Getting started GitHub repository find charts folder plgd hub Helm chart chart automatically published Helm registry https charts plgd dev during release Version chart sync appversion matching release tag e g 2 1 1 configuration values documented here Install Certificate Manager communication devices clients plgd hub secured plgd hub services simplify deployment certificate management Certificate Manager required dependency deployed Kubernetes cluster kubectl apply f https github com jetstack cert manager releases download v1 6 0 cert manager yaml Register plgd Helm Chart Registry helm repo add plgd https charts plgd dev helm repo update Hang tight grab latest chart repositories Successfully update plgd chart repository helm repo list NAME URL plgd https charts plgd dev helm search repo plgd NAME CHART VERSION APP VERSION DESCRIPTION plgd plgd dps 0 9 0 0 9 0 Helm chart plgd device provisioning service plgd plgd hub 2 7 15 2 7 15 Helm chart plgd hub Hub deployment Hub Deployment focuses deploying plgd hub serves central management system devices utilizing HTTP gRPC Cloud2Cloud API effectively control interact devices documentation offers detailed instructions information guide hub deployment process Learn Hub deployment Device Provisioning Service deployment Device Provisioning Service Deployment extends capabilities hub deployment introducing Device Provisioning Service service enables onboard devices hub seamlessly eliminating need manual intervention documentation outlines steps resources required deploying Device Provisioning Service Learn Device Provisioning Service deployment", + "objectID": "en/docs/deployment/deployment", + "description": "Overview of plgd deployments", + "docsOthersDisplay": true, + "date": "2023-05-24", + "categories": [ + "deployment", + "kubernetes" + ], + "keywords": [ + "deployment", + "kubernetes", + "k8s", + "helm", + "chart" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Device Provisioning Service", + "uri": "en/docs/deployment/device-provisioning-service", + "content": "", + "objectID": "en/docs/deployment/device-provisioning-service", + "weight": 20 + }, + { + "title": "Advanced Configuration", + "uri": "en/docs/deployment/device-provisioning-service/advanced", + "content": "Customize OAuth client credential flow production expected own OAuth server create OAuth client DPS support client credential flow case need add append OAuth client configuration global oauth device section global oauth device name plgd dps clientID clientSecret grantType clientCredentials scopes openid audience https api example com web clientID audience https example com Integration KeyCloak OAuth server section provides instructions integrate KeyCloak OAuth server integration involves configuring DPS OAuth client WWW OAuth client use value claim following steps will ensure appropriate user identified owner DPS devices begin need locate user id within KeyCloak OAuth server user will designated owner DPS devices Once obtained user id will substitute value subsequent instructions end integration process will establish connection OAuth DPS client user default association based value However wish change behavior option create custom mapper create custom mapper define specific logic sets appropriate value requirements allows tailor association user OAuth DPS client according specific needs process acquiring device access token OAuth server Device Provisioning Service incorporates query parameter request called parameter specifies desired value associated access token Create OAuth client DPS KeyCloak following configuration Settings Enabled Client Protocol openid connect Access Type confidential Service Accounts Enabled Authorization Enabled Credentials Client Authenticator Client Id Secret Secret Mapper Create custom Hardcoded claim mapper Token Claim Name Claim value Claim JSON Type String Add access token Add userinfo Create WWW OAuth client mapper adds claim user JWT token use User Property mapper following configuration map id property claim Settings Enabled Client Protocol openid connect Access Type public Standard Flow Enabled Valid Redirect URIs https www example com Backchannel Logout Session Required OpenID Connect Compatibility Modes Use Refresh Tokens Mapper Property id Token Claim Name Claim JSON Type String Add ID token Add access token Add userinfo helm chart add following configuration global ownerClaim authority oauth device name plgd dps clientID clientSecret grantType clientCredentials scopes openid audience https api example com redirectURL cloud plgd dps login callback web clientID audience https example com mockoauthserver enabled false deviceProvisioningService enrollmentGroups owner hub authorization provider name plgd dps clientId clientSecret audience https api example com scopes openid sure replace appropriate values setup apply modifications please follow instructions provided Deploy hub Device Provisioning Service Customize client certificates DPS first need set certificates secret kubectl n plgd create secret generic dps my client certs from file ca crt from file tls crt from file tls key ca crt CA certificate tls crt client certificate tls key client private key need add extraVolume extraVolumeMounts deviceProvisioningService section v deviceProvisioningService extraVolumeMounts name dps client certs mountPath certs my client certs extraVolumes name dps client certs secret secretName dps my client certs finally need set client tls section deviceProvisioningService section eg mongo deviceProvisioningService clients storage mongo tls ca certs my client certs ca crt cert certs my client certs tls crt key certs my client certs tls key", + "objectID": "en/docs/deployment/device-provisioning-service/advanced", + "description": "How to customize the Device Provisioning Service deployment", + "docsOthersDisplay": true, + "date": "2023-05-24", + "categories": [ + "deployment", + "kubernetes" + ], + "keywords": [ + "deployment", + "kubernetes", + "k8s", + "helm", + "chart" + ], + "weight": 40 + }, + { + "title": "Device Provisioning Service", + "uri": "en/docs/deployment/device-provisioning-service/device-provisioning-service", + "content": "deploy Device Provisioning Service will need follow instructions outlined provided page extend hub helm configuration basic deployment uses Mock OAuth Server so shall used test development purposes Use extra care production follow instructions Advanced configuration deploying Device Provisioning Service Kubernetes sure follow steps Hub first apply changes page configuration Once done deploy hub Device Provisioning Service Device Provisioning Service configuration values documented here Device provider Device Provisioning Service When device successfully attested against enrollment group Device Provisioning Service device s owner needs set owner configured enrollment group Therefore Device Provisioning Service needs obtain authorization code OAuth service associated owner When device contacts hub hub will exchange authorization code JWT access token contains owner claim owner Client credential flow client credential flow OAuth client linked its owner establish connection client include owner s details JWT access token setting owner claim access token serves multiple purposes sign in token authorization code sign up refresh token extend device s access hub When hub receives access token extracts owner s information it obtain new access token OAuth server hub appends owner query parameters using format enables hub authenticate retrieve appropriate access token associated owner OAuth server clientCredentials flow can t use sub claim owner OAuth client itself Therefore need utilize claim identify owner setting value DPS OAuth client WWW OAuth client establish connection user associated DPS devices connection via needs applied OAuth clients used accessing hub devices mock OAuth2 0 server need override default hub configuration s section new DPS WWW OAuth clients global ownerClaim https plgd dev owner mockoauthserver mockoauthserver oauth name plgd dps clientID test clientSecret test grantType clientCredentials scopes openid audience https api example com redirectURL https mock plgd cloud things name plgd web clientID test clientSecret test redirectURL https mock plgd cloud things scopes openid useInUi true production need set OAuth server client credential flow described Customize OAuth server client credential flow allow download Device Provisioning Service docker image k8s following configuration needs extend configuration deviceProvisioningService image dockerConfigSecret auths ghcr io auth access ghcr io please reach us connect plgd dev order request permission GitHub account access plgd device provisioning server images refer documentation instructions allow access Configure Enrollment Groups enrollment groups configured via deployment utilizing setup hub configuration populate values deviceProvisioningService enrollmentGroups attestationMechanism x509 certificateChain field please provide ECDSA certificate chain PEM format used sign device manufacturer certificate IDevId certificate chain include intermediate CA certificates root CA certificate order closest intermediate CA leaf root CA verify onboarding device step 4 value set information enrollment group configuration found here deviceProvisioningService enrollmentGroups id 98be12de 3991 4567 aeea edd9a656e6df owner 1 mockoauthserver preSharedKey 0123456789012345 client application attestationMechanism x509 certificate validation device manufacturer certificate IDevId certificateChain BEGIN CERTIFICATE MIIBaDCCAQ6gAwIBAgIQM6HFZ BMuyBspnPJEhPX9DAKBggqhkjOPQQDAjAUMRIw 7vHsqw2PCgAm9Qs3ZEQaKMZ2EGuPBvvXZXjPDA END CERTIFICATE hub authorization provider name plgd dps global oauth device name dps provider clientId test mockoauthserver clientSecret test mockoauthserver scopes openid successfully manage device local network sure set owner field corresponding SubjectId value configure preSharedKey Key login screen plgd client application preSharedKey not set device will managed via certificate authentication NodePort Device Provisioning Service install plgd hub microk8s io need enable nodePort Device Provisioning Service Device Provisioning Service apply following values deviceProvisioningService service type NodePort nodePort 15684 port set 15684 default port 5684 already used CoAP Gateway Service configuration applied test environment Deploy hub Device Provisioning Service deploy hub Device Provisioning Service apply following commands helm upgrade i n plgd create namespace f withMock yaml hub plgd plgd hub helm upgrade i n plgd create namespace f withMock yaml dps plgd plgd dps execute commands multiple times update configuration cases will need restart pods deleting them kubectl n plgd delete kubectl n plgd pods o name grep hub plgd kubectl n plgd delete kubectl n plgd pods o name grep dps plgd Final configuration mock ", + "objectID": "en/docs/deployment/device-provisioning-service/device-provisioning-service", + "description": "Running Device Provisioning Service on Kubernetes", + "docsOthersDisplay": true, + "date": "2023-05-18", + "categories": [ + "deployment", + "kubernetes" + ], + "keywords": [ + "deployment", + "kubernetes", + "k8s", + "helm", + "chart" + ], + "weight": 10, + "isMainSectionPage": true + }, + { + "title": "Troubleshooting", + "uri": "en/docs/deployment/device-provisioning-service/troubleshooting", + "content": "encounter issues Device Provisioning Service Hub follow steps enable debug logs configuration Update YAML configuration file following content coapgateway log dumpBody true level debug deviceProvisioningService log dumpBody true level debug Apply helm configuration running following commands helm upgrade i n plgd create namespace f withUpdatedMock yaml hub plgd plgd hub helm upgrade i n plgd create namespace f withUpdatedMock yaml dps plgd plgd dps Restart pods deleting them kubectl n plgd delete kubectl n plgd pods o name grep hub plgd kubectl n plgd delete kubectl n plgd pods o name grep dps plgd steps will enable debug logging restart necessary components providing detailed information troubleshooting issues Device Provisioning Service Hub Issue Device unable connect DPS device unable connect DPS follow steps Check DPS logs running following command kubectl n plgd logs kubectl n plgd pods o name grep dps plgd Check device logs console cases issue lies certificate chain resolving domain name it s certificate chain problem following Verify certificate chain correct order root CA last certificate chain Ensure certificate chain set deviceProvisioningService enrollmentGroups attestationMechanism x509 certificateChain field Confirm device certificates stored correct files HOME plgdcerts device pkicerts mfgkey pem HOME plgdcerts device pkicerts mfgkey pem HOME plgdcerts device pkicerts dpsca pem Issue Device unable connect Hub device unable connect Hub follow steps Check Hub logs running following command kubectl n plgd logs kubectl n plgd pods o name grep coap gateway Check device logs console cases issue related resolving domain name misconfigured provider it s provider configuration problem following Verify provider configuration set deviceProvisioningService enrollmentGroups hub authorization provider field Compare provider configuration DPS coap gateway provider configuration running following command kubectl n plgd kubectl n plgd configmap o name grep coap gateway o yaml yq data service yaml yq apis coap authorization providers Device connect DPS unable retrieve certificates authorization code device connect DPS service unable retrieve certificates certificate authority obtain authorization code due lack trust follow steps certificate authority need append certificate authority endpoint global authorizationCAPool set deviceProvisioningService enrollmentGroups hub certificateAuthority grpc tls caPool certs extra ca crt described Customize client certificates DPS section Alternatively create extra volume mount it set deviceProvisioningService enrollmentGroups hub certificateAuthority grpc tls caPool field CA volume authorization provider follow similar steps certificate authority set enrollmentGroups hub authorization provider http tls caPool", + "objectID": "en/docs/deployment/device-provisioning-service/troubleshooting", + "description": "How to troubleshooting issues with Device Provisioning Service", + "docsOthersDisplay": true, + "date": "2023-05-18", + "categories": [ + "deployment", + "kubernetes" + ], + "keywords": [ + "deployment", + "kubernetes", + "k8s", + "helm", + "chart" + ], + "weight": 30 + }, + { + "title": "Verify Device Onboarding", + "uri": "en/docs/deployment/device-provisioning-service/verify-device-onboarding", + "content": "verify device onboarding Device Provisioning Service Trusted Network Zero Trusted Network follow steps generate ECDSA root CA intermediate CA signing device manufacturer certificate IDevId option use tools OpenSSL plgd cert tool install cert tool execute following command shell go install github com plgd dev hub v2 tools cert tool latest Similarly install yq tool updating YAML files use following command go install github com mikefarah yq v4 latest Finally ensure go bin directory included PATH executing following command export PATH PATH go env GOPATH bin steps will enable generate necessary certificates configure environment appropriately Generate certificates Generate ECDSA root CA validity 100 years umask 0077 mkdir p HOME plgd_certs cd HOME plgd_certs go bin cert tool cmd generateRootCA outCert rootca crt outKey rootca key cert subject cn RootCA cert validFrom 2023 01 01T12 00 00Z cert validFor 876000h Generate ECDSA intermediate CA signed root CA validity 100 years umask 0077 cd HOME plgd_certs go bin cert tool cmd generateIntermediateCA signerCert rootca crt signerKey rootca key outCert intermediateca crt outKey intermediateca key cert basicConstraints maxPathLen 0 cert subject cn IntermediateCA cert validFrom 2023 01 01T12 00 00Z cert validFor 876000h Set maxPathLen 0 intermediate CA will sign leaf certificates device manufacturer certificate IDevId Generate device manufacturer certificate IDevId signed intermediate CA validity 100 years store mfgcrt pem mfgkey pem files umask 0077 mkdir p HOME plgdcerts device pkicerts cd HOME plgd_certs go bin cert tool cmd generateCertificate signerCert intermediateca crt signerKey intermediateca key outCert device pkicerts mfgcrt pem outKey device pkicerts mfgkey pem cert subject cn IDevId Device01 Set content intermediate_ca crt deviceProvisioningService enrollmentGroups attestationMechanism x509 certificateChain field using yq tool cd HOME cat withMock yaml yq e deviceProvisioningService enrollmentGroups 0 attestationMechanism x509 certificateChain cat plgdcerts intermediateca crt withUpdatedMock yaml helm upgrade i n plgd create namespace f withUpdatedMock yaml dps plgd plgd dps kubectl n plgd delete kubectl n plgd pods o name grep dps plgd Now test Device Provisioning Service following methods depending network trust level Onboarding device Zero trust network set Zero Trust network essential device authenticate Device Provisioning Service certificate Therefore acquire root certificate authority responsible signing device provisioning service save dpsca pem file specifically example device Obtain root certificate authority signs device provisioning service store dpsca pem file kubectl n plgd secret plgd ca o go template index data ca crt base64 d HOME plgdcerts device pkicerts dpsca pem Run example device device manufacturer certificate IDevId docker run it rm v HOME plgdcerts device pkicerts dps bin pki_certs ghcr io plgd dev device provisioning client dps cloud server debug latest test device coaps tcp example com 15684 real world scenario device manufacturer crucial ship device customers RootCA Root Certificate Authority Device Provisioning Service pre installed during manufacturing process ensures device trust certificates issued Device Provisioning Service RootCA securely embedded device s firmware modified firmware updates Additionally manufacturer provide customer Intermediate CA Intermediate Certificate Authority offer service allows obtain signed certificate specific device provisioning service Intermediate CA enables customer sign certificates devices ensuring secure communication within network Onboarding device Trusted network Trusted network device skip validation Device Provisioning Service certificate mode device doesn t need obtain root certificate authority signs device provisioning service file HOME plgdcerts device pkicerts dpsca pem exists remove following command rm HOME plgdcerts device pkicerts dpsca pem Run example device device manufacturer certificate IDevId docker run it rm v HOME plgdcerts device pkicerts dps bin pki_certs ghcr io plgd dev device provisioning client dps cloud server debug latest test device coaps tcp example com 15684 no verify ca specific use case requirement allow onboarding devices using vendor s Device Provisioning Service without validating Device Provisioning Service certificate However important note approach poses significant security risk real world scenario essential exercise caution consider potential consequences bypassing certificate validation potentially compromise security integrity network", + "objectID": "en/docs/deployment/device-provisioning-service/verify-device-onboarding", + "description": "How to test Device Provisioning Service", + "docsOthersDisplay": true, + "date": "2023-05-18", + "categories": [ + "deployment", + "kubernetes" + ], + "keywords": [ + "deployment", + "kubernetes", + "k8s", + "helm", + "chart" + ], + "weight": 20 + }, + { + "title": "IoT Hub", + "uri": "en/docs/deployment/hub", + "content": "", + "objectID": "en/docs/deployment/hub", + "weight": 10 + }, + { + "title": "Advanced Configuration", + "uri": "en/docs/deployment/hub/advanced", + "content": "Deployment Auth0 OAuth2 0 Server try plgd cloud instance available free uses Auth0 Identity Provider Example configuration enabling integration external OAuth2 0 Server contain OAuth2 0 configuration device Dashboard required values part global index echo global domain example com hubId d03a1bb4 0a77 428c b78c 1c46efe6a38e authority https myinstance auth0 com audience https api example com oauth device name onboardingtool mobile clientID l12j3oi12j3jlk1904 clientSecret 891y2ehpu2he9182heh2ep9128eh scopes offline_access redirectURL com example mobile login callback useInUi false name onboardingtool desktop clientID i0jt0i00xcva0r clientSecret 98219h23uh43t9r4h93rh994th923r scopes offline_access redirectURL https example com devices useInUi true web clientID 98y239hu94hr2ohu3e23eh withMock yaml helm upgrade i n plgd create namespace f withMock yaml hub plgd plgd hub configure OAuth server necessary enable redirect URL permits redirect within domain web client web client utilizes redirects display pages within user interface UI instance when accessing https example com devices deviceId UI OAuth flow utilizes opened URL redirect_uri Therefore essential authorize https example com valid redirect URL enable access subpage within UI Custom Authorization CA pool default plgd hub Helm chart expect certificate used OAuth 2 0 server signed CA rest certificates used plgd hub services including custom authorization CA pool authorization section use following configuration attribute global Custom CA certificate authorization endpoint PEM format authorizationCAPool BEGIN CERTIFICATE custom authorization CA pool PEM format END CERTIFICATE Please integrate own PKI signing certificates used plgd hub services production environment detailed instructions this refer link Using Let s encrypt certificates default plgd hub Helm chart issues self signed CA certificate used sign domain certificates exposed services encrypt external communication certificates signed Let s Encrypt CAs create issuer echo apiVersion cert manager io v1 kind ClusterIssuer metadata name letsencrypt prod spec acme server https acme v02 api letsencrypt org directory email info example com privateKeySecretRef name letsencrypt prod solvers http01 ingress class public issuer yaml kubectl apply f issuer yaml Required values plgd hub Helm chart makes use newly created signer are certmanager external issuer kind ClusterIssuer name letsencrypt prod global enableWildCartCert false Troubleshooting Issue Unable fetch data well known endpoint browser encounter error message unable fetch data well known endpoint when using plgd Dashboard likely due usage self signed certificate not trusted resolve issue need import plgd certificate authority CA system Follow steps below obtain public key Open terminal command prompt Execute following command kubectl n plgd secret plgd ca o go template index data ca crt base64 d running command will retrieve plgd CA s public key", + "objectID": "en/docs/deployment/hub/advanced", + "description": "How to customize the IoT Hub deployment", + "docsOthersDisplay": true, + "date": "2021-11-01", + "categories": [ + "deployment", + "kubernetes" + ], + "keywords": [ + "deployment", + "kubernetes", + "k8s", + "helm", + "chart" + ], + "weight": 20 + }, + { + "title": "IoT Hub", + "uri": "en/docs/deployment/hub/hub", + "content": "Quickest install own instance plgd hub use Mock OAuth2 0 Server option enabled no authentication available JWT token automatically issued default user Mock OAuth Server utilized testing development purposes Exercise additional caution when using it production environments please follow deployment instructions provided Advanced Configuration section ensure proper setup echo global domain example com hubId d03a1bb4 0a77 428c b78c 1c46efe6a38e mockoauthserver enabled true withMock yaml helm upgrade i n plgd create namespace f withMock yaml hub plgd plgd hub use microk8s similar kubernetes system ensure ingress dns storage add ons enabled Additionally configure Kubernetes cluster resolve private domain example com designated DNS server microk8s use microk8s enable dns DNS_SERVER set DNS server Deployment plgd hub Kubernetes cluster initiated Status deployment verified calling kubectl n plgd all When pods running plgd Dashboard will become available configured domain e g https example com NodePort CoAP Gateway install plgd hub microk8s io required enable nodePort CoAP Gateway Service extend port range K8S API Server extend port range add service node port range 5683 32767 var snap microk8s current args kube apiserver CoAP Gateway Service apply following values coapgateway service type NodePort nodePort 5684 configuration applied test environment Deploying Production order deploy Device Provisioning Service production environment please refer Advanced Configuration section detailed instructions", + "objectID": "en/docs/deployment/hub/hub", + "description": "Running hub on Kubernetes", + "docsOthersDisplay": true, + "date": "2021-11-01", + "categories": [ + "deployment", + "kubernetes" + ], + "keywords": [ + "deployment", + "kubernetes", + "k8s", + "helm", + "chart" + ], + "weight": 10, + "isMainSectionPage": true + }, + { + "title": "Device to Device Client", + "uri": "en/docs/device-to-device-client", + "content": "", + "objectID": "en/docs/device-to-device-client", + "weight": 6 + }, + { + "title": "Client Initialization", + "uri": "en/docs/device-to-device-client/client-initialization", + "content": "Client Application Ownership ways setup authentication devices clients plgd hub various deployment models supported It s distribution right credentials applies client applications needs authenticate communicate devices Deployment scenarios options initialize client provision right security credentials depends deployment scenarios use cases Let s go 2 deployment scenarios Devices single client Requirements Devices owned provisioned single client installation Devices accessed single client installation No centralized identity provider place device client custom application using device client Go library plgd d2d client scenario client generates or preconfigured credentials device it s going provision client needs persist credentials securely a pre shared key case credentials lost reinstallation disk failure factory reset device need executed using it s hardware button device native mechanism It s API not accessible client cannot authenticate default configuration plgd d2d client Pre shared key generated during startup no authentication plgd d2d client place Devices plgd hub 1 n clients Requirements Devices provisioned optionally onboarded plgd hub Ownership transfer done either DPS client Device ownership centralized driven identity provider Devices accessed remotely plgd hub API Devices discovered configured locally using client scenario allows clients part security domain plgd hub communicate securely devices Goal devices clients plgd hub trusting other Comparing previous use case client issues it s own pre shared key use case requires distribution Identity Certificates entities devices plgd hub clients Identity Certificate used authentication identifies users customers devices IDs entities known owner IDs deployment scenario requires plgd hub 1 n clients read further understand provision client Identity Certificate Client credential provisioning Identity Certificate issued Certificate Authority service part plgd hub deployment Default certificate delivered hub deployment package operator use custom certificate certificate used authentication data encryption plgd hub clients devices provision client Identity Certificate issued Certificate Authority service security domain entities plgd hub d2d client devices Identity Certificate issued Certificate Authority considered security domain Client requests identity certificate it s own option requires plgd d2d client application using device client Go library access plgd hub API client required issue CSR send certificate signing service Identity Certificate retrieving certificate initialization client becomes member security domain allows successfully authenticate interact device member security domain startuml Sequence skinparam backgroundColor grey hide footbox actor U User box D2D Client participant S Web App n running browser participant C Service n local remote host end box box plgd hub participant CA Certificate Authority participant OA OAuth 2 0 Server end box U C Open Web App activate U C S Serve UI deactivate C activate S S U Request plgd hub endpoint U S plgd hub endpoint S OA Request authorization code OA U Provide credentials U OA Username password return Authorization code S OA Exchange user token return User token S C Initialize n User token C CA Sign D2D Client Identity Certificate n CSR User token return Identity Certificate chain C C Initialize return Initialized S U Initialized U S Discover devices S C Discover devices enduml User agent mediates CSR client case plgd d2d client application using device client Go library cannot access plgd hub API directly e g it s running different network web service user s PC can CSR propagated browser plgd hub API response certificate authority service returned back browser client flow delivers Identity Certificate client without private key leaving client client communicate securely devices part security domain right receiving Identity certificate its initialization startuml Sequence skinparam backgroundColor grey hide footbox actor U User box D2D Client participant S Web App n running browser participant C Service n local remote host end box box plgd hub participant CA Certificate Authority participant OA OAuth 2 0 Server end box U C Open Web App activate U C S Serve UI deactivate C activate S S U Request plgd hub endpoint U S plgd hub endpoint S OA Request authorization code OA U Provide credentials U OA Username password return Authorization code S OA Exchange user token return User token S OA well known jwks json return jwks json S C Initialize n jwks json User token return Identity certificate challenge n D2D Client Identity CSR state S CA Sign D2D Client Identity CSR n CSR User token return Identity Certificate chain S C Finish Initialize n Identity Certificate Chain User token state return Initialized S U I", + "objectID": "en/docs/device-to-device-client/client-initialization", + "description": "How to initialize the client?", + "date": "2022-08-25", + "categories": [ + "d2d", + "client" + ], + "keywords": [ + "client", + "initialization", + "identity" + ], + "weight": 2 + }, + { + "title": "Overview", + "uri": "en/docs/device-to-device-client/overview", + "content": "Communicate device directly without backend Machine machine communication required interoperable scenarios one device needs notify one device needs retrieve configuration different one plgd platform together IoTivity support deployment scenarios communication models easiest develop machine machine interactions test device use plgd d2d client plgd d2d client using device client Go library exposes it s API HTTP gRPC endpoints built in UI allows discover devices add IP own interact it s resources", + "objectID": "en/docs/device-to-device-client/overview", + "description": "What is plgd Device to Device client?", + "date": "2022-08-18", + "categories": [ + "d2d", + "client" + ], + "keywords": [ + "d2d", + "client", + "proximity", + "udp" + ], + "weight": 1 + }, + { + "title": "Ownership Transfer and Provisioning", + "uri": "en/docs/device-to-device-client/ownership-transfer", + "content": "Device Ownership plgd d2d client become owner new unowned device Supported ownership transfer methods plgd d2d client are Just Works Manufacturer Certificate Supported credentials provisioned device verify client are Pre shared key Identity Certificate default configuration plgd d2d client provisions device pre shared key generated during startup one used every device Own device Part device ownership transfer credentials provisioning know d2d client initialization options depending setup request provision credentials requirements flow applies device credential provisioning Devices single client note deployment option here note pre shared key setup device D2D client service startuml Sequence skinparam backgroundColor grey hide footbox box D2D Client participant S Web App n running browser participant C Service n local remote host end box participant D Device n in local network Service S C Own device C D Set PreSharedKey return return Device owned enduml Client requests identity certificate its own note deployment option here note d2d client service requests identity certificate plgd Certificate Authority device its own startuml Sequence skinparam backgroundColor grey hide footbox box D2D Client participant S Web App n running browser participant C Service n local remote host end box participant D Device n in local network Service box plgd hub participant CA Certificate Authority end box S C Own device n User token C D Identity CSR return Identity CSR C CA Sign Device Identity Certificate n CSR User token return Device Identity chain C D Set Identity chain n Device Identity chain return C S Device owned deactivate C enduml User agent mediates CSR client note deployment option here note d2d client service unable reach plgd Certificate Authority service Therefore plgd d2d web app gets Identity CSR d2d client service requests certificate plgd Certificate Authority its own sent back d2d client service web app mediator role assuming PC it s loaded access both plgd hub d2d client service startuml Sequence skinparam backgroundColor grey hide footbox box D2D Client participant S Web App n running browser participant C Service n local remote host end box participant D Device n in local network Service box plgd hub participant CA Certificate Authority end box S C Own device n User token activate S C D Identity CSR return Identity CSR C S Identity certificate challenge n Device Identity CSR state S CA Sign Device Identity CSR n CSR User token return Identity Certificate Chain S C Finish Own n Identity Certificate Chain User token state C D Set Identity chain n Device Identity chain return return Device owned deactivate C deactivate S enduml", + "objectID": "en/docs/device-to-device-client/ownership-transfer", + "description": "How does security work with d2d?", + "date": "2022-08-18", + "categories": [ + "d2d", + "client" + ], + "weight": 3 + }, + { + "title": "Client Usage", + "uri": "en/docs/device-to-device-client/usage", + "content": "Device Discovery Devices discovered sending CoAP multicast message waiting configured timeout responses devices available subnet case want interact device cannot discovered using multicast either it s not subnet multicast blocked add device IP Discovered devices different device ownership states devices new unowned already owned ownership devices unowned state using configured ownership transfer method transferred you exactly defined information ownerID found here document let s focus ownership transfer use cases device credentials WIP", + "objectID": "en/docs/device-to-device-client/usage", + "description": "How to work with the d2d client?", + "date": "2022-08-18", + "categories": [ + "d2d", + "client" + ], + "keywords": [ + "d2d", + "client", + "discovery", + "udp", + "ownership" + ], + "weight": 4 + }, + { + "title": "Features", + "uri": "en/docs/features", + "content": "", + "objectID": "en/docs/features", + "weight": 2 + }, + { + "title": "Control Plane", + "uri": "en/docs/features/control-plane", + "content": "", + "objectID": "en/docs/features/control-plane", + "weight": 20 + }, + { + "title": "Control Plane", + "uri": "en/docs/features/control-plane/control-plane", + "content": "control plane system provides various interfaces functionalities managing devices controlling operations handling maintenance tasks overview different components features control plane Device IoT Hub Device IoT Hub communication facilitated CoAP Gateway allowing bidirectional communication devices IoT Hub HTTP API HTTP API RESTful API allows users manage devices system provides user friendly interface performing maintenance tasks managing device metadata controlling devices either cloud local network HTTP API built top CoAP Gateway Resource Directory handle communication devices Link HTTP API Documentation GRPC API GRPC API protocol buffer based API enables users manage devices system offers simple intuitive interface performing maintenance tasks managing device metadata controlling devices cloud local network GRPC API built top CoAP Gateway Resource Directory Link GRPC API Documentation Device Twin device twin IoT Hub represents current state device s resource Whenever connected device undergoes changes notifies IoT Hub using CoAP Gateway observations observations initiated soon device successfully connects authenticates hub changes made device stored audit log EventStore latest version device twin made available clients Resource Directory Learn Device Twin JetStream EventBus IoT Hub services utilize NATS default EventBus MongoDB EventStore However cases direct subscription internal messaging system necessary bypassing IoT Hub gateways simplify data reconciliation enable easier scaling consumers IoT Hub supports alternative EventBus called JetStream JetStream built top NATS persists published events utilizing JetStream EventBus users access older as yet unprocessed messages without directly accessing EventStore Learn JetStream EventBus Pending Commands command issued converted event placed pending state awaiting processing one gateways primarily CoAP Gateway When pending event processed gateway triggers execution confirmation command converted confirmation event device offline event remains pending until processed timetolive parameter set command limit waiting time specify its expiration Once event expires hub no longer processes it possible cancel resource command resulting confirmation event status set Canceled However cancellation command issued confirmation cancellation fails pending command expires canceled confirmation command executed confirmation command fails Learn Pending Commands Device Device Device Device D2D feature enables users control devices directly local network allows users access devices without going cloud useful performing maintenance tasks managing devices conveniently D2D feature built top plgd d2d client handle communication devices Learn Device device", + "objectID": "en/docs/features/control-plane/control-plane", + "description": "What are the control plane features of plgd system?", + "date": "2023-05-23", + "categories": [ + "zero-touch", + "provisioning. features" + ], + "keywords": [ + "provisioning", + "TPM", + "device-twin" + ], + "isMainSectionPage": true, + "weight": 1 + }, + { + "title": "Device Twin", + "uri": "en/docs/features/control-plane/device-twin", + "content": "device twin represents current state device s resource connected device notifies plgd hub every change using CoAP Gateway observations started right device successfully connects authenticates changes persisted form audit log EventStore latest version returned clients Resource Directory twin kept date Update resource CoAP Gateway device resources updated services users time resource change requests called Pending Commands soon command successfully processed device CoAP Gateway informed change observation channel details following diagram startuml Sequence skinparam backgroundColor grey hide footbox entity OCF Server Server participant Gateway Gateway participant Resource Aggregate ResourceAggregate control Event Bus Bus entity Client Client Client ResourceAggregate UpdateResourceRequest activate Client activate ResourceAggregate ResourceAggregate Client UpdateResourceResponse ResourceAggregate Bus ResourceUpdatePending deactivate ResourceAggregate Bus Gateway ResourceUpdatePending activate Gateway Gateway Server UPDATE oic r temperature activate Server Server Gateway OK deactivate Server Gateway ResourceAggregate ConfirmResourceUpdateRequest activate ResourceAggregate ResourceAggregate Gateway ConfirmResourceUpdateResponse deactivate Gateway ResourceAggregate Bus ResourceUpdated deactivate ResourceAggregate Bus Client ResourceUpdated deactivate Client Resource changed Update device twin Server Gateway NOTIFY oic r temperature changed activate Gateway Gateway ResourceAggregate NotifyResourceChangedRequest activate ResourceAggregate ResourceAggregate Gateway NotifyResourceChangedResponse deactivate Gateway ResourceAggregate Bus ResourceChanged deactivate ResourceAggregate Server Gateway NOTIFY oic r temperature changed enduml Update resource OCF Client device actuated local network temperature room changed user updated resource device to device connectivity example using plgd client change triggers notify device delivers CoAP Gateway subscribed device observer information change updates twin plgd hub details following diagram startuml Sequence skinparam backgroundColor grey hide footbox entity OCF Client Client entity OCF Server Server participant Gateway Gateway participant Resource Aggregate ResourceAggregate control Event Bus Bus Client Server UPDATE oic r temperature Server Client OK Resource changed Update device twin Server Gateway NOTIFY oic r temperature changed activate Gateway Gateway ResourceAggregate NotifyResourceChangedRequest activate ResourceAggregate ResourceAggregate Gateway NotifyResourceChangedResponse deactivate Gateway ResourceAggregate Bus ResourceChanged deactivate ResourceAggregate Server Gateway NOTIFY oic r temperature changed enduml Device Metadata Twin State Device metadata contains additional information device lifecycle including connection status twin synchronization state twin synchronization state informs user reconciliation reconnect twin creation first sign in plgd hub states various edge cases so let s go diagrams understand state transitions during device lifecycle Device successfully signs in startuml Sequence skinparam backgroundColor grey hide footbox entity Device Device participant CGW CoAP Gateway participant RA Resource Aggregate participant EB Event Bus Device CGW Sign activate Device CGW RA UpdateDeviceMetadataRequest with nConnected Status ONLINE alt DeviceMetadataUpdated TwinEnabled true RA EB DeviceMetadataUpdated with nConnected Status ONLINE TwinSynchronization State OUTOFSYNC else RA EB DeviceMetadataUpdated with nConnected Status ONLINE TwinSynchronization State DISABLED end RA CGW deactivate RA return Signed deactivate Device enduml Twin synchronization starts synchronization described following sequence diagram occurs batch observe supported device default plgd hub requires support batch observe Devices doesn t support disconnected you re interested twin synchronization state transition works devices without batch observe support jump here startuml Sequence skinparam backgroundColor grey hide footbox entity Device Device participant CGW CoAP Gateway participant RA Resource Aggregate participant EB Event Bus Device CGW Publish resources activate Device CGW Device Published resources deactivate Device CGW RA UpdateDeviceMetadataRequest with nTwinSynchronization State SYNCING RA EB DeviceMetadataUpdated with nTwinSynchronization State SYNCING RA CGW deactivate RA activate Device alt ForceResynchronization false CGW Device Batch observe incremental changes ETAGs Device CGW BatchNotifyResourceChangedRequest incremental changes else ForceResynchronization true CGW Device Batch observe Device CGW Current representation resources end CGW RA BatchNotifyResourceChangedRequest increment changes RA EB ResourceChanged event c", + "objectID": "en/docs/features/control-plane/device-twin", + "description": "What is device twin?", + "docsOthersDisplay": true, + "date": "2021-05-13", + "categories": [ + "features" + ], + "keywords": [ + "twin", + "twin", + "cache", + "history" + ], + "weight": 30 + }, + { + "title": "Entity-tag (ETAG)", + "uri": "en/docs/features/control-plane/entity-tag", + "content": "entity tag ETAG used identify changes resource happen time ETAG generated resource server case device using various methods version checksum hash timestamp When client retrieves entity tag treat opaque value without making assumptions its content structure CoAP ETAG part CoAP options used detect changes resources used optimize client processing time response device case no change detected ETAG wasn t changed last request information ETAG refer RFC7252 Section 5 10 6 IoTivity lite Definitions ETAG ETAG 8 byte opaque value represents state resource generated device used detect changes resources Global ETAG Global ETAG highest ETAG value generated among resources device used generate next ETAG when resource created modified Collision collision happens when client cached resource specific ETAG value device ETAG associated different resource state Collisions occur when lack synchronization device s time Random number number within range 1 1000 ETAG Generation Algorithm IoTivity lite ETAG generated using following algorithm Obtain current time current global ETAG value current time exceeds global ETAG value update global ETAG value current time Generate random number add global ETAG value obtain new resource ETAG modified resource Assign generated ETAG step 3 modified resource its new ETAG value following algorithm ETAG always increasing unique changed resource among resources device When handling load operations global ETAG value determined taking maximum value among existing ETAGs combining current time adding random number refer ocetagloadandclear inclusion time component serves minimize potential collisions ETAGs device resources cached ETAGs stored clients Additionally introduction random number introduces element uncertainty ETAG particularly cases time synchronization not precise Collision example Consider device always sets time 1 1 1970 due lack real time clock device one modifiable resource Let s say device running updated resource ETAG value 1000 client ETAG value 1000 cached However due power loss subsequent restart with no stored ETAGs persistent storage random number generator returns 1 previous run Meanwhile client updates resource exact time previous run modifies different property resulting ETAG 1000 resource initial client without knowledge resource modification made second client sends request access resource using previously cached ETAG value 1000 device responds VALID code indicating ETAG remains valid Nonetheless first client remains unaware resource altered client device s resource continues possess ETAG static uint64t getag static uint64t etagrandom return ocrandomvalue 1000 1 void ocetaginit getag occlocktime etagrandom new ETAG changed resource uint64t ocetag_get void uint64t occlock_time now g_etag g_etag now getag getag etag_random return g_etag Updating ETAG Device two methods updating ETAG when resource changes ocnotifyresourcechanged function internally triggers ocnotifyobservers observable resource ocresourceupdateetag ocresourceupdate_etag function updates ETAG without informing observers change content beneficial resources not observable ETAG Usage Clients order improve network traffic efficiency clients option store received ETAGs responses cache determine ETAG valid client send ETAGs request device ETAG valid device will respond VALID code no body corresponding matched ETAG ETAG not valid device will respond CONTENT code containing current ETAG corresponding body OCF interfaces ETAG remains unaffected even different representations resource available except batch interface oic if b ETAG specifically tied state resource itself regardless interface used ETAG Batch interface oic res When accessing oic res resource ETAG represents highest ETAG value among device resources collection collection ETAG itself multiple resources within collection undergo simultaneous changes ETAG will set highest value among modified resources client sends request ETAG matches highest ETAG value among resources response will consist VALID code without body However ETAG provided client does not match highest ETAG value response will include CONTENT code along content resources highest ETAG value among them support use ETAGs representation resource batch response extended introducing etag property following structure href ocf rep etag 1 8 byte opaque value identify specific resource ETAG used batch ETAG response client conduct comparison ETAG value resource within batch response ETAG value provided CoAP option client case collection resource ETAG used ETAG not included body response Incremental Changes incremental changes feature enables clients request modifications resources occurred recent notification observation request request incremental changes device request clients include ETAG 0 Value CoAP option along multiple CoAP query parameters using following format incChanges in", + "objectID": "en/docs/features/control-plane/entity-tag", + "description": "What is ETAG?", + "docsOthersDisplay": true, + "date": "2021-05-13", + "categories": [ + "features" + ], + "keywords": [ + "twin", + "twin", + "cache", + "history" + ], + "weight": 31 + }, + { + "title": "gRPC API", + "uri": "en/docs/features/control-plane/grpc-api", + "content": "", + "objectID": "en/docs/features/control-plane/grpc-api", + "description": "gRPC Gateway API", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate" + ], + "weight": 20 + }, + { + "title": "HTTP API", + "uri": "en/docs/features/control-plane/http-api", + "content": "", + "objectID": "en/docs/features/control-plane/http-api", + "description": "HTTP Gateway API", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate" + ], + "weight": 10 + }, + { + "title": "JetStream", + "uri": "en/docs/features/control-plane/jetstream", + "content": "default plgd hub services use NATS EventBus MongoDB EventStore use cases require subscription directly internal messaging system instead communicating plgd using its gateways simplify data reconciliation scale consumers easier plgd supports JetStream technology alternative EventBus JetStream built top NATS persisting published events Using JetStream EventBus allows access older not yet processed messages without accessing EventStore edge cases when plgd event couldn t published JetStream stored EventStore case need identify one event lost needed retrieve using plgd gRPC Gateway information JetStream found here NATS subjects overview Definitions ownerID owner device calculated uuid NewV5 uuid NamespaceURL value JWT ownerClaim deviceID UUID device hrefID identifier resource calculated uuid NewV5 uuid NamespaceURL href href resource path eg oic d Device events event compressed snappy encoded protobuf devices event envelope event envelope consist Event data containing event Event event_type describing type event Resource links plgd owners ownerID devices deviceID resource links eventType publishes resource links events types resourcelinkspublished resourcelinksunpublished resourcelinkssnapshottaken device deviceID ownerID Metadata events plgd owners ownerID devices deviceID metadata eventType publishes metadata events types devicemetadataupdatepending devicemetadataupdated devicemetadatasnapshottaken device deviceID ownerID Resources events plgd owners ownerID devices deviceID resources hrefID eventType publishes resources events types resourcechanged resourcecreated resourcecreatepending resourcedeleted resourcedeletepending resourceretrieved resourceretrievepending resourcestatesnapshottaken resourceupdated resourceupdatepending resource hrefID deviceID ownerID Owner events event encoded protobuf event envelope compressed snappy Registration events plgd owners ownerID registrations eventType publishes owner events types devicesregistered devicesunregistered ownerID Consumer subscriptions options consumers events subscribe to plgd owners retrieves events hub plgd owners ownerId retrieves events owner ownerId plgd owners devices deviceId retrieves events device deviceId plgd owners devices deviceId resource links retrieves resource link events device deviceId plgd owners devices deviceId resource links resourcelinkspublished retrieves resourcelinkspublished event device deviceId plgd owners devices resource links retrieves resource link events devices plgd owners ownerId devices resource links retrieves resource link events devices belonging owner ownerId plgd owners devices deviceId metadata retrieves metadata events device deviceId plgd owners devices deviceId metadata devicemetadataupdated retrieves devicemetadataupdated event device deviceId plgd owners devices metadata retrieves metadata events devices plgd owners ownerId devices metadata retrieves metadata events devices belonging owner ownerId plgd owners devices deviceId resources retrieves resource events device deviceId plgd owners devices deviceId resources hrefId retrieves events resource hrefId device deviceId plgd owners devices deviceId resources hrefId resourcechanged retrieves resourcechanged events resource hrefId device deviceId plgd owners devices deviceId resources resourcechanged retrieves resourcechanged events resources device deviceId plgd owners devices resources resourcechanged retrieves resourcechanged events resources devices plgd owners devices resources hrefId resourcechanged retrieves resourcechanged events resource hrefId devices plgd owners ownerId devices resources resourcechanged retrieves resourcechanged events resources devices belonging owner ownerId plgd owners ownerId devices resources hrefId resourcechanged retrieves resourcechanged events resource hrefId devices belonging owner ownerId Enable JetStream Deployment JetStream EventBus will controlled single configuration option available plgd HELM chart currently WIP It s required create event streams JetStream used plgd EventBus streams not created plgd services won t work Enable jetstream plgd bundle Set env variable JETSTREAM true bundle docker run it rm e JETSTREAM true network host v pwd tmp data data ghcr io plgd dev hub bundle latest Enable jetstream manually Required nats server 2 3 Required nats client Enable jetstream nats server Append jetstream configuration nats config nats server jetstream storedir JETSTREAMPATH 1GB memory maxmemorystore 1073741824 10GB memory maxfilestore 10737418240 information nats server configuration start it nats server c nats config Setup create stream Setup events stream stream json events hub will stored name EVENTS name Stream may not spaces tabs period greater asterisk subjects list subjects consume supports wildcards plgd ", + "objectID": "en/docs/features/control-plane/jetstream", + "description": "How to persist plgd events in the JetStream", + "date": "2021-07-01", + "categories": [ + "features" + ], + "keywords": [ + "persistence", + "message log", + "nats" + ], + "weight": 80 + }, + { + "title": "Pending command", + "uri": "en/docs/features/control-plane/pending-command", + "content": "command hub converted events eg create resource converted ResourceCreatePending event retrieve resource converted ResourceRetrievePending event update resource converted ResourceUpdatePending event delete resource converted ResourceDeletePending event update device metadata converted DeviceMetadataUpdatePending event events wait processing one gateway mostly coap gateway When one gateways process pending event executes one confirmation command converted event confirm resource create converted confirmation event ResourceCreated confirm resource retrieve converted confirmation event ResourceRetrieved confirm resource update converted confirmation event ResourceUpdated confirm resource delete converted confirmation event ResourceDeleted confirm device metadata update converted confirmation event DeviceMetadataUpdated Expiration cancellation When device not online event waits processing limits wait set timetolive command defines expiration When event expires hub doesn t process anymore cancel resource command produces confirmation event status Canceled cancel update device metadata produces confirmation event set Canceled Races cancellation command occurs confirmation cancellation fails pending command expires canceled execution confirmation command confirmation command fails case 3 scenarios retrieve doesn t change state device hub update hub notified current state resources observation creation hub notified created resource via publishing delete hub notified deleted resource via unpublishing update device metadata gateway revert previous state", + "objectID": "en/docs/features/control-plane/pending-command", + "description": "What is pending command?", + "date": "2021-08-04", + "categories": [ + "features" + ], + "keywords": [ + "command", + "history" + ], + "weight": 50 + }, + { + "title": "Features", + "uri": "en/docs/features/features", + "content": "Secured Onboarding Devices plgd system incorporates Secured Onboarding Devices feature guarantees secure dependable procedure incorporating devices system functionality encompasses various tasks overseeing device identity certificates integrating root certification authorities generating providing per device chain trust certificates line OCF specifications system relies X 509 certificates device identity authentication purposes Learn Secured Onboarding Devices Control Plane Control Plane feature enables users manage devices system includes ability perform maintenance tasks manage device metadata control devices cloud local network Learn Control Plane Monitoring Diagnostics Monitoring Diagnostics feature enables users monitor diagnose system includes ability view device status check device health monitor system performance Learn Monitoring Diagnostics", + "objectID": "en/docs/features/features", + "description": "What are the features of plgd system?", + "date": "2023-05-23", + "categories": [ + "zero-touch", + "provisioning. features" + ], + "keywords": [ + "provisioning", + "TPM", + "device-twin" + ], + "isMainSectionPage": true, + "weight": 1 + }, + { + "title": "Monitoring and Diagnostics", + "uri": "en/docs/features/monitoring-and-diagnostics", + "content": "", + "objectID": "en/docs/features/monitoring-and-diagnostics", + "weight": 30 + }, + { + "title": "Audit Log", + "uri": "en/docs/features/monitoring-and-diagnostics/audit-log", + "content": "audit log context IoT Hub system comprehensive record events actions occur within system serves valuable tool tracking monitoring analyzing user activities system events event captured audit log contains essential components AuditContext EventMetadata AuditContext component provides important contextual information user involved event includes userid field stores identifier user responsible action allows administrators track attribute specific events individual users Additionally correlationid field used establish correlation related events actions enables grouping analysis events part larger workflow process EventMetadata component provides additional details metadata event version field within EventMetadata represents monotonically increasing number without gaps specifically used event sourcing events allowing ordering consistency within event stream timestamp field records exact date time when event occurred facilitating chronological sequencing analysis connection_id field identifies specific connection associated event providing insights network session context event took place helps identifying source origin event Additionally sequence field not filled event types may used certain events ResourceChanged event skip older events process recent data efficiently maintaining audit log provided components administrators effectively monitor review system activities track user actions ensure compliance security policies investigate security breaches policy violations log serves valuable source information analysis troubleshooting maintaining integrity security IoT Hub system Event Deduplication ResourceChanged two occasions when ResourceChange event skipped when sequence when duplicate Metadata data latest event stored snapshot used check whether problematic case occurred order events not guaranteed thus duplicate events occur avoid event carries metadata metadata unique identifier connection triggered event sequence number event given connection simple algorithm uses two values ensures older data doesn t overwrite check whether event not out of sequence given connection following simple algorithm used isTheSameConnection compare connection identifier event connection identifier snapshot metadata isTheSameConnection isValidSequence sequence number event greater sequence number snapshot metadata not isValidSequence return false overwrite metadata snapshot metadata current event return true Thus subsequent events connection no interweaving connections invalid sequence numbers skipped second circumstance events skipped when data event itself didn t change check whether data updated following algorithm used hasTheSameData compare event data snapshot event data hasTheSameData return false overwrite event data snapshot current event data return true not out of sequence check data changed check succeed event added event store ResourceLinksPublished Duplicate publishing resource avoided ensure snapshot map published resources stored map stores resources key value pairs href resource used key resource itself value Resources added updated map whenever ResourceLinksPublished event occurs Resources removed map whenever ResourceLinksUnpublished event occurs resources ResourceLinksPublished event examined newly published updated resources will kept event Resources already published no changes data will filtered out algorithm follows Resource event Resource snapshot map Resource data equal resource data snapshot map remove Resource event else add update Resource snapshot map no resources published remain event event skipped it s not added event store ResourceLinksUnpublished ResourceLinksUnpublished event contains list resource hrefs unpublished avoid storing unnecessary unpublish events event store snapshot map ResourceLinksPublished used determine resources currently published thus unpublished algorithm works follows Resource Href event Resource Href exists key snapshot map remove Resource Href snapshot map else remove Resource Href event algorithm hrefs previously published remain event added event store unpublished hrefs removed snapshot map Additionally one special case ResourceLinksUnpublished event contains empty list hrefs currently published resources unpublished snapshot map cleared DeviceMetadataUpdated similar technique one utilized ResourceChanged used avoid adding duplicate subsequent DeviceMetadataUpdated events event store last handled DeviceMetadataUpdated event saved used skip unnecessary events hasTheSameData compare event data saved event data hasTheSameData return false overwrite saved event data current event data return true Thus subsequent DeviceMetadataUpdated events without data changes skipped not added event store", + "objectID": "en/docs/features/monitoring-and-diagnostics/audit-log", + "description": "What is Audit Log and how does it work?", + "date": "2021-06-11", + "categories": [ + "features" + ], + "keywords": [ + "duplicated events", + "audit log", + "device twin" + ], + "weight": 90 + }, + { + "title": "Disaster Recovery", + "uri": "en/docs/features/monitoring-and-diagnostics/disaster-recovery", + "content": "Resiliency understood readapt crisis situation applies infrastructure data means varies user user service disruptions users okay retrieving latest resource value others require changes occurred during time application internal messaging system down failure scenario when node hosting plgd CoAP Gateway crashes Thousands devices will try reconnect keep device twin date creates huge load rapidly slows down system not handled properly plgd hub offers users various techniques approach disaster recovery case error system failure detected Let s look them Event Data Loss plgd hub event driven system implemented using CQRS EventSourcing design patterns event occurs system e g when content resource changes when new resource published when new device registered plgd hub stored EventStore published EventBus plgd Gateways subscribed EventBus notify gRPC stream WebSockets requested changes Using plgd Gateways straightforward option communicate system provide both current value resource set events representing changes particular resource audit log active subscription plgd events using gRPC WebSockets NATS JetStream fail publish operation executed plgd service multiple reasons cannot prevent infrastructure failure when node went down service crash operator failure during roll out able system back in sync state failure detected data reconciliation process started Missing Events Detection Sometimes obvious events lost service consuming plgd events restarted due crash network outage infrastructure failure high chance missed events scenario service shall start right away it s running data reconciliation process Another not so obvious event data loss occur due EventBus service disruptions during short network outage service wasn t restarted messaging client just missed one event service subscribed events requires processing events correct order skipping one event not accepted service needs track version event case received event s version isn t incremented one compared latest event service shall start resource reconciliation process Data Reconciliation using gRPC Interest latest resource content plgd gRPC Gateway exposes GetEvents RPC call retrieve latest version resource case not interested changes occurred during outage right sync Additionally optimize operation timestamp ETag specified Just latest event persisted pass timestamp EventMetadata argument no update resource occurred specified time won t receive resource data Interest missed events require retrieval events occurred during outage GetEvents RPC call used responsibility find newest timestamp among events retrieve resources global timestamp ETag set value expected format timestamps Unix time nanoseconds response events published specified time Described RPC call plgd gRPC Gateway supports global ETag ETag per resource Additionally apply device id resource id filters limit request predefined set devices and or resources Data Reconciliation using JetStream plgd hub uses NATS EventBus keeping events persisted EventStore MongoDB use cases plgd hub users interested using JetStream EventBus subscribe it option built in deployment easily enabled configuring helm chart TODO Having JetStream EventBus gives possibility read stored events service outage right JetStream instead requesting data plgd gRPC Gateway plgd hub doesn t guarantee delivery events EventBus guarantees events stored EventStore correct order case JetStream NATS failure plgd hub not able publish events won t published again service anyway fallback reconciliation using plgd gRPC Gateway", + "objectID": "en/docs/features/monitoring-and-diagnostics/disaster-recovery", + "description": "Getting back online and in-sync", + "date": "2021-06-16", + "categories": [ + "features" + ], + "keywords": [ + "disaster recovery", + "data reconciliation", + "jetstream" + ], + "weight": 70 + }, + { + "title": "KeepAlive", + "uri": "en/docs/features/monitoring-and-diagnostics/keepalive", + "content": "Device iotivity lite KeepAlive CoAP Gateway Once device connected coap gateway signed in sends ping signal every 20 seconds verify connection sending ping device waits response known pong 4 seconds no response received during time delay pings decreased 4 seconds device misses six consecutive pings without response will initiate reconnect process behavior process configured set callback function using occloudset_keepalive CoAP Gateway KeepAlive Device CoAP gateway keepalive function check connection device interval sending pings timeout waiting response pong configured variable CoAP gateway s helm settings coapgateway apis coap keepAlive timeout default interval set 20 seconds CoAP gateway does not receive data connection set ping interval will send ping device device does not respond within timeout period coapgateway apis coap keepAlive timeout will disconnected", + "objectID": "en/docs/features/monitoring-and-diagnostics/keepalive", + "description": "How keepalive works with plgd hub", + "date": "2023-01-10", + "categories": [ + "features" + ], + "keywords": [ + "keepalive", + "timeout", + "iotivity-lite", + "coap-gateway" + ], + "weight": 40 + }, + { + "title": "Monitoring and Diagnostics", + "uri": "en/docs/features/monitoring-and-diagnostics/monitoring-and-diagnostics", + "content": "Audit Log audit log comprehensive record events actions within system tracks user activities system events providing valuable information monitoring analysis security audit log consists two main components AuditContext EventMetadata AuditContext contains contextual information user involved event user ID correlation ID EventMetadata provides additional details event including version timestamp connection ID sequence audit log helps administrators track user actions ensure compliance investigate security breaches Learn Audit Log Traceability Tracing used track progression request within system context distributed tracing spans represent units work within trace forming tree like structure Spans contain span context globally unique identifiers provide metrics related request error duration RED Tracing helps debug availability performance issues Learn Traceability Monitoring Device Connection Monitoring device connections involves two aspects device keepalive CoAP gateway CoAP gateway keepalive devices device using iotivity lite protocol sends ping signal CoAP gateway every 20 seconds no response received within 4 seconds ping interval decreased device misses six consecutive pings reconnect process initiated Similarly CoAP gateway sends pings devices no response received within specified timeout period device disconnected Learn Monitoring Device Connection Disaster Recovery Disaster recovery crucial maintaining system resilience data integrity plgd hub offers various techniques handle failures errors case event data loss events missed due service disruptions network outages data reconciliation processes initiated Missing events detected comparing event versions obvious scenarios service restarts Data reconciliation performed using gRPC calls retrieve latest resource content missed events JetStream EventBus provides alternative option reading stored events service outages Learn Disaster Recovery", + "objectID": "en/docs/features/monitoring-and-diagnostics/monitoring-and-diagnostics", + "description": "What are the monitoring and diagnostic features of plgd system?", + "date": "2023-05-23", + "categories": [ + "zero-touch", + "provisioning. features" + ], + "keywords": [ + "provisioning", + "TPM", + "device-twin" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Monitoring Device Connectivity", + "uri": "en/docs/features/monitoring-and-diagnostics/monitoring-device-connectivity", + "content": "CoAP gateway responsible connection management including date representation device status information driven Resource Aggregate command UpdateDeviceMetadata gets initiated when device connection status changes device connects disconnects CoAP Gateway However various scenarios consider unexpected termination CoAP Gateway due factors node failure power loss others Managing Service Heartbeat Updates context managing CoAP gateways associated devices process setting devices offline state involves series structured steps Generating Unique Service ID instance CoAP gateway initiates unique ID generated during startup IDs stored database reference associated metadata device Sending Heartbeat Periodically CoAP gateway sends heartbeat using UpdateServiceMetadata command update heartbeat entries managed Resource Aggregate request includes service ID time live TTL timestamp indicating when request created request transformed event it s successfully stored event store During command to event transformation Resource Aggregate calculates heartbeatValidUntil based time live duration request latest heartbeats no longer valid set new event expired case heartbeat update late previous one already expired it s present expired list update operation fails requesting CoAP Gateway terminated sending self destruct signal SIGTERM UpdateServiceMetadata function exclusively designed internal service usage Consequently command does not rely JWT authorization essential note function not accessible public endpoints Authentication using mutual TLS authentication place Updating Device Status soon Resource Aggregate identifies expired CoAP Gateways marks expired procedure set devices previously connected Gateway offline starts Devices whose connection maintained matching service ID identified status set offline using standard UpdateDeviceMetadata command audit context command contains nil uuid user ID Once devices undergone update Resource Aggregate initiates ConfirmOfflineServices procedure purges offline gateways event store Handling Response response ServicesMetadataUpdated contains validity heartbeat helps CoAP Gateway decide when send next heartbeat next heartbeat scheduled intervals one third until service s expiration deadline denoted returned heartbeatValidUntil startuml Sequence skinparam backgroundColor grey hide footbox participant CoAPGateway CoAP Gateway participant ResourceAggregate Resource Aggregate participant EventBus Event Bus CoAPGateway CoAPGateway Generate Unique ID return Unique ID CoAPGateway ResourceAggregate Send UpdateServiceMetadataRequest with nTTL ID Timestamp return UpdateServiceMetadataResponse with nheartbeatValidUntil activate CoAPGateway loop every 1 3 until heartbeatValidUntil CoAPGateway ResourceAggregate Send UpdateServiceMetadataRequest with nTTL Service ID Timestamp ResourceAggregate ResourceAggregate Process ServicesMetadataUpdated with nValid Expired service s heartbeats ResourceAggregate CoAPGateway Send UpdateServiceMetadataResponse with nheartbeatValidUntil deactivate CoAPGateway loop expired service s heartbeat loop device associated offline service ResourceAggregate ResourceAggregate Send UpdateDeviceMetadataRequest with nDevice ID Connection Status OFFLINE ResourceAggregate EventBus Publish DeviceMetadataUpdated with nConnection Status OFFLINE Connection ServiceId AuditContext UserId 00000000 0000 0000 0000 000000000000 end ResourceAggregate ResourceAggregate Confirm offline service end deactivate ResourceAggregate end Device Online CoAPGateway ResourceAggregate Send UpdateDeviceMetadataRequest with nDevice ID Connection Status ONLINE ServiceId Service ID ResourceAggregate EventBus Publish DeviceMetadataUpdated with nConnection Status ONLINE Connection ServiceId Service ID return UpdateDeviceMetadataResponse enduml Example series steps describes process expanding setup encountering Memory event recording analyzing gateway states identifying gateway termination within Kubernetes environment using CoAP gateways Resource Aggregate Initial Sequence Added two CoAP Gateways Kubernetes k8s environment Configured 1 minute time live so CoAP Gateway will update its metadata every minute current time Wed Sep 27 2023 13 47 20 GMT 0000 Event Store two CoAP Gateways valid heartbeats valid id ID 0 heartbeatValidUntil 1695822490000000000 Wed Sep 27 2023 13 48 10 GMT 0000 id ID 1 heartbeatValidUntil 1695822500000000000 Wed Sep 27 2023 13 48 20 GMT 0000 expired OOM Event Restart One gateway instance ID 1 experiences Memory OOM event restarts Two CoAP Gateway instances exist concurrently ID 0 ID 2 ID 1 dead heartbeat valid current time Wed Sep 27 2023 13 47 30 GMT 0000 valid id ID 0 heartbeatValidUntil 1695822490000000000 Wed Sep 27 2023 13 48 10 GMT 0000 id ID 1 Dead instance heartbeatValidUntil 1695822500000000000 Wed Sep 27 2023 13 48 20 G", + "objectID": "en/docs/features/monitoring-and-diagnostics/monitoring-device-connectivity", + "description": "Learn how to determine the online or offline status of connected devices", + "date": "2023-08-08", + "categories": [ + "features", + "iot-connectivity" + ], + "keywords": [ + "service", + "coap-gateway", + "network-monitoring" + ], + "weight": 2 + }, + { + "title": "Open Telemetry Tracing", + "uri": "en/docs/features/monitoring-and-diagnostics/open-telemetry-tracing", + "content": "Traces track progression single request called trace request may initiated user application Distributed tracing form tracing traverses process network security boundaries unit work trace called span trace tree spans Spans objects represent work done individual services components involved request flows system span contains span context set globally unique identifiers represent unique request span part of span provides Request Error Duration RED metrics used debug availability performance issues information traces specification covers concepts including trace span parent child relationship span context attributes events links example shows open telemetry tracing action plgd Open Telemetry plgd hub services emit telemetry collectors secured using TLS supporting otlp encoding open telemetry integration enabled globally plgd hub helm chart Read further information enable open telemetry plgd hub helm chart request content included gRPC CoAP Gateway spans HTTP Gateway proxy gRPC Gateway request content found gRPC Gateway spans Setup Open Telemetry collector Interested deploy OpenTelemetry Collector Read here Don t forget enable TLS receivers otlp protocols grpc endpoint 0 0 0 0 55680 tls Set want verify client certificate clientcafile certs root_ca crt cert_file certs cert crt key_file certs cert key Setup plgd hub enable tracing plgd services need set following variables plgd helm chart global openTelemetryExporter enabled true address grafana agent demo svc cluster local 55680 Service certificates those used secure internal communication plgd hub services reused secure communication collector Example clients servers golang Initialize tracer package test import context google golang org grpc go opentelemetry io otel go opentelemetry io otel exporters otlp otlptrace otlptracegrpc go opentelemetry io otel propagation go opentelemetry io otel sdk resource sdktrace go opentelemetry io otel sdk trace semconv go opentelemetry io otel semconv v1 10 0 func initTracer ctx context Context sdktrace TracerProvider res err resource New ctx resource WithAttributes service name used display traces backends semconv ServiceNameKey String myService err nil panic err dial otel collector conn err grpc Dial otel collector 4317 err nil panic err Set trace exporter traceExporter err otlptracegrpc New ctx otlptracegrpc WithGRPCConn conn err nil _ conn Close panic err Register trace exporter TracerProvider using batch span processor aggregate spans export bsp sdktrace NewBatchSpanProcessor traceExporter tracerProvider sdktrace NewTracerProvider sdktrace WithSampler sdktrace AlwaysSample sdktrace WithResource res sdktrace WithSpanProcessor bsp set global trace provider otel SetTracerProvider tracerProvider set global propagator tracecontext the default no op otel SetTextMapPropagator propagation NewCompositeTextMapPropagator propagation TraceContext propagation Baggage return tracerProvider Setup HTTP Client package test import context fmt io ioutil log net http go opentelemetry io contrib instrumentation net http otelhttp func main tp initTracer context Background defer func err tp Shutdown context Background err nil log Printf Error shutting down tracer provider v err c http Client Transport otelhttp NewTransport http DefaultTransport req _ http NewRequestWithContext context Background GET http localhost 7777 hello nil res err c Do req err nil panic err defer res Body Close body err ioutil ReadAll res Body err nil panic err fmt Printf Response Received s n n n body Setup HTTP Server package main import context io log net http github com plgd dev hub v2 pkg opentelemetry otelhttp func main tp initTracer context Background defer func err tp Shutdown context Background err nil log Printf Error shutting down tracer provider v err helloHandler func w http ResponseWriter req http Request io WriteString w Hello world n otelHandler otelhttp NewHandler http HandlerFunc helloHandler Hello http Handle hello otelHandler err http ListenAndServe 7777 nil err nil panic err Setup GRPC Client package main import context log go opentelemetry io contrib instrumentation google golang org grpc otelgrpc google golang org grpc func main tp initTracer context Background defer func err tp Shutdown context Background err nil log Printf Error shutting down tracer provider v err conn err grpc Dial localhost 7777 grpc WithUnaryInterceptor otelgrpc UnaryClientInterceptor grpc WithStreamInterceptor otelgrpc StreamClientInterceptor setup credentials jwt token err nil panic err defer conn Close c api NewHelloServiceClient conn Setup GRPC Server package main import context log net ", + "objectID": "en/docs/features/monitoring-and-diagnostics/open-telemetry-tracing", + "description": "How to trace request through plgd hub?", + "docsOthersDisplay": true, + "date": "2022-05-19", + "categories": [ + "features" + ], + "keywords": [ + "opentelemetry", + "tracing" + ], + "weight": 60 + }, + { + "title": "Secured Onboarding of Devices", + "uri": "en/docs/features/secured-onboarding-devices", + "content": "", + "objectID": "en/docs/features/secured-onboarding-devices", + "weight": 10 + }, + { + "title": "Secured Onboarding of Devices", + "uri": "en/docs/features/secured-onboarding-devices/secured-onboarding-devices", + "content": "Secured Onboarding Devices feature plgd system ensures secure reliable procedure incorporating devices system encompasses various tasks managing device identity certificates integrating root certification authorities generating per device chain trust certificates system relies X 509 certificates device identity authentication purposes following OCF specifications Device Identity Certificate Management Device Identity Certificate Management component handles generation provisioning per device chain trust certificates ensures device unique trusted certificate secure communication within system TPM Integration TPM Integration feature facilitates integration Trusted Platform Modules TPMs devices TPMs microcontroller chips provide hardware based security computer systems feature validates verifies TPMs enhancing overall security devices system Learn TPM Integration Certificate Authority Integration Certificate Authority Integration feature enables integration certificate authorities CAs system ensures validation verification certificates issued trusted CAs further enhancing security trustworthiness system Automatic Device Provisioning Automatic Device Provisioning feature enables devices automatically provisioned system simplifies accelerates onboarding process reducing manual intervention saving time effort Device Provisioning Service DPS excellent choice various provisioning scenarios connect configure devices IoT Hub Learn Device Provisioning Service", + "objectID": "en/docs/features/secured-onboarding-devices/secured-onboarding-devices", + "description": "What are the Secured Onboarding of Devices features of plgd system?", + "date": "2023-05-23", + "categories": [ + "zero-touch", + "provisioning. features" + ], + "keywords": [ + "provisioning", + "TPM", + "device-twin" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Securing device with TPM", + "uri": "en/docs/features/secured-onboarding-devices/tpm", + "content": "TPM Trusted Platform Module microcontroller chip provides hardware based security computer systems used securely store manage cryptographic keys including private keys various types certificates SSL TLS certificates IDevID certificates IDevID Identity Device certificates digital certificates used authenticate IoT devices contain public key digital signature issued trusted Certificate Authority CA storing private key IDevID certificates TPM certificate s security device authenticates safeguarded against unauthorized access malicious attacks OCF Certificates TPM Device OCF Open Connectivity Foundation uses certificates ensure secure communication devices services via mTLS When TPM Trusted Platform Module integrated private key stored TPM credential resource contains public certificate reference key private key TPM default message digest algorithm allowed SHA256 want allow SHA384 call following function ocseccertsmdsetalgorithmsallowed MBEDTLSX509IDFLAG MBEDTLSMD_SHA256 MBEDTLSX509IDFLAG MBEDTLSMD_SHA384 Similarly default elliptic curve group allowed secp256r1 want allow secp384r1 call following function ocseccertsecpsetgroupids_allowed MBEDTLSX509IDFLAG MBEDTLSECPDPSECP256R1 MBEDTLSX509IDFLAG MBEDTLSECPDPSECP384R1 OCF Manufacturer Certificate manufacturer certificate used during ownership transfer device acts server manufacturer certificate client certificate required mTLS certificate used device connect device service cloud meet requirements manufacturer certificate extended key usage EKU include Server authentication Client authentication without Extended Key Usage signature algorithm either ecdsa with SHA256 ecdsa with SHA384 elliptic curves secp256r1 secp384r1 OCF Identity Certificate OCF identity certificate serves purpose identifying device network enabling connect client devices services clouds certificate used when device already provisioned signed identity certificate ownership transfer allows device act server device factory reset certificate deleted new device UUID created create certificate device resource oic sec csr provides generated CSR Certificate Signing Request meet requirements identity certificate extended key usage EKU include Server authentication Client authentication 1 3 6 1 4 1 44924 1 6 without Extended Key Usage signature algorithm either ecdsa with SHA256 ecdsa with SHA384 elliptic curves secp256r1 secp384r1 subject common name format uuid GUID device UUID default message digest signature algorithm identity CSR SHA256 However need use SHA384 need allowed ocseccertsmdsetalgorithmsallowed call following function ocseccertsmdsetsignaturealgorithm MBEDTLSMDSHA384 Similarly default elliptic curve group identity CSR secp256r1 want use secp384r1 need allowed ocseccertsecpsetgroupids_allowed call following function ocseccertsecpsetgroupid MBEDTLSECPDP_SECP384R1 TPM Integration OCF certificates typically stored credential resource oic sec cred using PEM DER RAW formats TPM integrated private key kept within TPM credential resource holds public certificate along reference key pointing private key TPM way private key related functions handled TPM including data signing encryption reference key either public key its hash used IDevID Certificate OCF Manufacturer Certificate manufacturer certificate IDevID certificate signed certificate authority used certificate stored credential resource oic sec cred PEM DER RAW format TPM private key stored TPM credential resource contains IDevID certificate IDevID reference key private key TPM store IDevID certificate credential resource use call ocpkiaddmfgcert reference key instead private key Generating OCF Identity Certificate generate OCF identity certificate private key first generated TPM associated reference key public key reference key will stored oic sec cred private key used TPM sign CSR Certificate Signing Request sent certificate authority generate certificate CSR signed multiple times example certificate rotation recommended remove private key when factory reset performed Integration iotivity lite integrate TPM iotivity lite mbedtls library used cryptography four main functions need implemented Generate public private key mbedtlspkecpgenkey function generates private key CSR identity certificate when iotivity lite doesn t private key keypair storage function private key needs generated TPM public key mbedtlspkcontext needs filled Free private key TPM pkfreekey function frees private key TPM function called when factory reset performed when keypair storage does not match TPM during generation CSR reference key Store reference key credential resource mbedtlspkwritekeyder function writes reference key buffer credential resource keypair storage reference key associated private key TPM needs created according mbedtlspkcontext pk Load public key reference key mbedtlspkparsekey function parses public key certificate reference key keypair storage credential resource reference key private key TPM written mbedtlspkwri", + "objectID": "en/docs/features/secured-onboarding-devices/tpm", + "description": "How TPM can enhance security with iotivity-lite?", + "date": "2023-04-28", + "categories": [ + "features" + ], + "keywords": [ + "features", + "security", + "tpm" + ], + "weight": 110 + }, + { + "title": "Introduction", + "uri": "en/docs/introduction", + "content": "", + "objectID": "en/docs/introduction", + "weight": 1 + }, + { + "title": "What is plgd", + "uri": "en/docs/introduction/what-is-plgd", + "content": "biggest problems IoT current market IoT solutions fall short IoT considered Put way What common issues preventing companies fully realizing benefits IoT question answered DZone 23 executives involved Internet Things Observations Companies not able not talent complete end to end solution unrealized complexity deployment lack skills so Lack seamless secure data fabric platform Challenging something scale maintaining quality Creating scalable devices connect everything need to Large amount data will run IoT will stored hub IoT industry across numerous market verticals impasse customers demanding increasing sophistication lower prices Given complexity importance IoT no single company dictating path forward entire industry viable path forward collaboration companies market verticals collaborate developing testing standardizing non differentiating functionality Open Connectivity Foundation currently working achieve that however device hub communication represents unique challenge engineers involved historical need engineers become knowledgeable embedded systems cloud native application development proposed solution problem emulate container runtime interface CRI architecture embody Conway s law establish loose coupling IoT code CoAP IoTivity portions system familiar cloud developers ex db messaging auth will vary depending use case Challenges Embedded systems engineering cloud native application development likely orthogonal skill sets organizations whose products benefit internet connectivity immense complexity managing own deployment means market requires managed services no seamless portability IoT devices clouds Extremely important want decouple networking costs hardware costs customers cell phones Lack industry standard increases attack surface industry plgd Goals Address challenges easy companies public clouds adopt offer managed service Ensure loose coupling database messaging auth plgd hub implementation Run system demonstrates integrate database messaging auth serve default choice companies common OLTP use cases", + "objectID": "en/docs/introduction/what-is-plgd", + "description": "What is plgd and how can it help you?", + "date": "2021-05-13", + "categories": [ + "overview", + "fundamentals" + ], + "keywords": [ + "overview", + "introduction" + ], + "weight": 1 + }, + { + "title": "Quickstart", + "uri": "en/docs/quickstart", + "content": "", + "objectID": "en/docs/quickstart", + "weight": 4 + }, + { + "title": "Contribute", + "uri": "en/docs/quickstart/contribute", + "content": "guide will describe setup environment enable contribution development Development Linux Ubuntu 20 02 LTS Install Go a Follow official golang installation guide b Use update golang script options install golang usr local go everything work correctly add path go environment PATH variable Add following line HOME profile file export PATH PATH usr local go bin Restart may needed changes profile file applied test go setup correctly run terminal go version command succeed print currently installed version go Checkout hub go workspace install go modules dependencies parts hub repository sensitive location code source code repository reside go workspace HOME go src plgd dev hub Manually create folder structure use git clone recursive download source code dependencies cd HOME go mkdir p src github com plgd dev cd src github com plgd dev git clone recursive git github com plgd dev hub git successful checkout use go mod download go mod tidy commands download dependencies cd HOME go src plgd dev hub go mod download go mod tidy Install building tools Execute following command terminal sudo apt install build essential Install Docker Follow official docker installation guide Additionally succesfull docker installation allow non root users use docker so follow Manage Docker non root user guide Install protobuf compiler Services use protobuf messages communicate generate pb files proto files protoc binary used Makefiles install latest protoc following steps Download latest protoc zip zip file contains two folders bin include a move contents extracted bin folder usr local bin b move contents extracted include folder usr local include Set permissions copied files folders chmod 0755 read write execute owner read execute group world steps automated convenience script hub tools install install latest protoc py Install protoc modules generate protobuf definitions gRPC Gateway automatically generate API clients server stubs golang protoc plugins gRPC Gateway used install run go install github com grpc ecosystem grpc gateway main protoc gen grpc gateway github com grpc ecosystem grpc gateway main protoc gen openapiv2 google golang org protobuf cmd protoc gen go google golang org grpc cmd protoc gen go grpc Test environment system fully setup capable compiling code repository Test go compilation running unit tests test command succeed execute available unit test repository Test protobuf generation proto generate", + "objectID": "en/docs/quickstart/contribute", + "description": "Contribute to development", + "date": "2021-07-09", + "categories": [ + "quickstart" + ], + "keywords": [ + "quickstart", + "development" + ], + "weight": 5 + }, + { + "title": "Deploy Hub", + "uri": "en/docs/quickstart/deploy-plgd-hub", + "content": "multiple ways start using testing plgd hub own infrastructure you re just trying touch IoT framework go back Control device remotely tutorial use free try plgd cloud instance case want touch system localy Docker installed use plgd hub Bundle Kubernetes read deploy plgd hub Kubernetes using helm chart continue here plgd Bundle Bundle deployment hosts core plgd hub services mocked OAuth Server single Docker image services hosts gRPC HTTP API proxied NGINX configurable NGINX_PORT FQDN Client application used Control device remotely works bundle Bundle version plgd services used simple testing development purposes Performance evaluations production environment sensitive deployments deploy plgd services using plgd HELM chart Run localhost deploy access plgd hub local PC using bundle run single command docker run d name plgd p 443 443 p 5683 5683 p 5684 5684 ghcr io plgd dev hub bundle latest couple seconds plgd hub will become available plgd dashboard opened browser https localhost Note bundle issues it s own self signed certificate needs accepted browser Authorization plgd hub doesn t work without OAuth Server not require developers not interested sharing bundle instances users simple OAuth2 0 Mock Server included bundle Authentication plgd therefore not required test user automatically logged in applies device connections case you re using bundle devices connecting CoAP Gateway use random static onboarding code it s not verified Onboarding devices therefore simpler OAuth Server part plgd testing development purposes production integration plgd external OAuth2 0 server required Troubleshooting default plgd hub bundle hosts NGINX proxy port 443 port already occupied process e g Skype Default port changed environment variable e NGINX_PORT 8443 Please aware port needs exposed container p 443 443 needs changed match new port e g p 8443 8443 Logs data default stored data path Run container v PWD vol plgd data data able analyze logs case issue case need support happy support Gitter OCF UCI Cloud2Cloud Gateway not part bundle", + "objectID": "en/docs/quickstart/deploy-plgd-hub", + "description": "Secure remote device communication made easy. Follow our guide to deploy the plgd hub in your environment with simple steps.", + "docsTitleDisplay": true, + "docsTitleIndex": 3, + "date": "2023-02-03", + "categories": [ + "quickstart" + ], + "keywords": [ + "quickstart", + "bundle", + "deployment", + "d2c" + ], + "weight": 3 + }, + { + "title": "Local Discovery", + "uri": "en/docs/quickstart/local-discovery", + "content": "guide will walk process discovering on boarding controlling secure OCF Device using plgd client application PC Installation Client Application Using Docker Image proceed run client application ensure Docker already installed computer run client application execute following command terminal docker run rm it e NUM_DEVICES 1 p 8080 8080 ghcr io plgd dev client application latest Docker image comes virtual device discovered local network setting value NUM_DEVICES specify number virtual devices discovered local network wish modify client application s configuration mount config yaml file Docker container path plgd config yaml logs client application found tmp client application log file within Docker container Installation Linux Windows MacOS Cloud Server running Raspberry Pi machine local network Firstly download latest version client application operating system Below example download run client application Linux curl https github com plgd dev client application releases download v0 5 0 client application0 5 0linuxamd64 tar gz output client application0 5 0linuxamd64 tar gz tar xzf client application0 5 0linux_amd64 tar gz cd client application0 5 0linux_amd64 client application Use Client Application Client Application running PC application opened port access browser via http localhost 8080 running client application client application will automatically create config yaml file www directory current directory onboard devices try plgd cloud use config yaml file read change config yaml continue here Initializing Client Application default client application will ask set Subject ID Key first time Subject ID unique identifier client application Key password communication devices Subject ID Key will used authenticate device pressing Initialize button client application will store Subject ID Key config yaml file Discovering Devices Local Network initializing client application discovery devices local network will start automatically client application will discover devices local network display list devices web page Discover button appends new devices list devices remove old devices please click Flush Cache button Discover Transfer ownership On boarding Click unowned device open device section that just click Own button that Subject ID Key becomes owner device device needs support OCF Secure Specification without oscore iotivity lite needs compiled DOCSECUREENABLED ON DOCOSCOREENABLED OFF cmake flag reset ownership OCF device click Disown button Onboard device hub Once device owned on boarded hub onboard device hub click Onboard button hub configuration set config yaml file device will onboarded hub automatically Otherwise will need fill modal window onboard configuration hub obtain configuration hub open hub UI click Device button enter device ID copy configuration hub modal window client application modal window that device will onboarded hub onboarded hub device support OCF Device Cloud Services Specification iotivity lite needs compiled DOCCLOUDENABLED ON CMake flag off board device hub click Offboard button that device will off boarded hub Update Retrieve resource device update retrieve resource device locate resource list discovered devices click its name will open modal window displaying resource s details including its value resource type attributes update resource modify value field click Update button retrieve resource click Retrieve button", + "objectID": "en/docs/quickstart/local-discovery", + "description": "Discover, update and subscribe to changes with ease! This guide will show you how to find your device, update its properties and stay up-to-date.", + "docsTitleDisplay": true, + "docsTitleIndex": 2, + "date": "2023-02-03", + "categories": [ + "quickstart" + ], + "keywords": [ + "quickstart", + "discovery", + "coap", + "multicast", + "d2d" + ], + "weight": 2 + }, + { + "title": "Remote Access", + "uri": "en/docs/quickstart/remote-access", + "content": "try plgd cloud try plgd hub without downloading single docker container going try plgd cloud Additionally client application used onboard IoTivitiy Lite OCF standardized devices plgd hub order use client application need use config yaml file contains configuration plgd hub ca crt file contains certificate plgd hub need directory client application binary client application run following command client application config config yaml Once application running open http localhost 3000 browser Onboarding device requires Discover devices go specific device own it finally onboard it config yaml file log level info encoding console stacktrace enabled false level warn encoderConfig timeEncoder rfc3339nano apis http enabled true address 3000 tls enabled false caPool null keyFile certFile clientCertificateRequired false readTimeout 8s readHeaderTimeout 4s writeTimeout 16s idleTimeout 30s cors allowedOrigins allowedHeaders Accept Accept Language Accept Encoding Content Type Content Language Content Length Origin X CSRF Token Authorization allowedMethods PATCH HEAD POST PUT OPTIONS DELETE allowCredentials false ui enabled true directory www grpc enabled false address 8081 enforcementPolicy minTime 5m0s permitWithoutStream false keepAlive maxConnectionIdle 0s maxConnectionAge 0s maxConnectionAgeGrace 0s time 0s timeout 0s tls enabled false caPool null keyFile certFile clientCertificateRequired false clients device coap maxMessageSize 262144 inactivityMonitor timeout 10s blockwiseTransfer enabled true blockSize 1024 ownershipTransfer methods justWorks manufacturerCertificate tls caPool null keyFile certFile tls authentication x509 remoteProvisioning ownerClaim owner id hubID 1c10a3b6 287c 11ec ac2d 13054959c274 coapGateway coaps tcp try plgd cloud 5684 authority https auth plgd cloud realms shared certificateAuthority https api try plgd cloud webOAuthClient clientID LXZ9OhKWWRYqf12W0B5OXduqt02q0zjS audience https try plgd cloud scopes openid deviceOAuthClient clientID cYN3p6lwNcNlOvvUhz55KvDZLQbJeDr5 audience scopes offline_access providerName plgd web d2d localhost 3000 mode userAgent userAgent csrChallengeStateExpiration 1m0s caPool ca crt ca crt file BEGIN CERTIFICATE MIIBZjCCAQugAwIBAgIRAKtzI VSfFl46j6bSAcm NYwCgYIKoZIzj0EAwIwEjEQ MA4GA1UEAxMHcGxnZC1jYTAeFw0yMjEwMTcyMTEyMTNaFw0yMzEwMTcyMTEyMTNa MBIxEDAOBgNVBAMTB3BsZ2QtY2EwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAR4 igB2lVcxggiGPBt4t6Qv2TcMf 1YGhWNpZ8 tCGHcIIhAVvxs2MafErth24fNbiQ Mj XQM7aq5xRpOsHyKQ5o0IwQDAOBgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH BAUw AwEB zAdBgNVHQ4EFgQUp5ONBSJGMxEecSYMSQKr4i96PpwwCgYIKoZIzj0EAwID SQAwRgIhAN0xA9BXNkEkfLqAgdqmPKhVdt rgZPVLTu4bRtx2 PDAiEAhQWL4NqT aFPz IQs1 0I 7WaTP7l4fUMa G3a3oYTsQ END CERTIFICATE", + "objectID": "en/docs/quickstart/remote-access", + "description": "Ensure secure remote communication with your device. This guide walks you through the onboarding process to the plgd hub.", + "docsTitleDisplay": true, + "docsTitleIndex": 4, + "date": "2023-02-03", + "categories": [ + "quickstart" + ], + "keywords": [ + "quickstart", + "onboarding", + "dashboard", + "d2c" + ], + "weight": 4 + }, + { + "title": "Start Device", + "uri": "en/docs/quickstart/start-device", + "content": "guide will walk process starting secure Device using IoTivity library Raspberry Pi Requirements Raspberry Pi board microSD card Raspberry Pi OS Optional HDMI monitor cable USB keyboard mouse Pi Ethernet Wi Fi connection DHCP enabled network Pi Personal computer Linux MacOS recommended network Pi Setting Raspberry Pi set Raspberry Pi please follow step by step tutorial Enabling SSH highly recommended simplifies access device allows changes quickly information available here Enable SSH via Desktop Launch Raspberry Pi Configuration Preferences menu Navigate Interfaces tab Select Enabled next SSH Click OK enable SSH via raspi config terminal Enter sudo raspi config terminal window Select Interfacing Options Navigate select SSH Choose Yes Select Ok Choose Finish Connect Raspberry Pi via SSH information access Raspberry Pi remotely found here ssh pi raspberryPiIpAddress Default login username pi password raspberry didn t change Install essential build tools sudo apt get update apt get install build essential git curl openssl cmake Install IoTivity Cloud Server example Checkout IoTivity Lite execute commands Raspberry Pi git clone https github com iotivity iotivity lite git recursive cd iotivity lite Build Cloud Server example mkdir build cd build cmake DCMAKEBUILDTYPE Release DCMAKEVERBOSEMAKEFILE ON DBUILDTESTING OFF DOCCLOUDENABLED ON DOCCOLLECTIONSIFCREATEENABLED ON DOCMNTENABLED ON DOCOSCOREENABLED OFF DOCRESOURCEACCESSINRFOTMENABLED ON DOCDISCOVERYRESOURCEOBSERVABLEENABLED ON DPLGDDEVTIME_ENABLED ON cloud_server Run Cloud Server example cd apps cloud_server Now Cloud Server example running Raspberry Pi allows discover device connect plgd hub", + "objectID": "en/docs/quickstart/start-device", + "description": "Get your device up and running in seconds! Follow this guide for easy setup, and start exploring the power of plgd using a real hardware or a virtual device.", + "docsTitleDisplay": true, + "docsTitleIndex": 1, + "date": "2023-02-03", + "categories": [ + "quickstart" + ], + "keywords": [ + "quickstart", + "device", + "iotivity" + ], + "weight": 1 + }, + { + "title": "Services", + "uri": "en/docs/services", + "content": "", + "objectID": "en/docs/services", + "weight": 7 + }, + { + "title": "Certificate Authority", + "uri": "en/docs/services/certificate-authority", + "content": "", + "objectID": "en/docs/services/certificate-authority", + "weight": 10 + }, + { + "title": "Certificate Authority", + "uri": "en/docs/services/certificate-authority/certificate-authority", + "content": "PLGD Certificate Authority CA responsible issuing OCF Open Connectivity Foundation identity certificates users devices certificates obtained signing Certificate Signing Requests CSRs subject strict security measures Certificate Signing Request CSR Certificate Signing Request CSR request sent PLGD CA user device seeking issuance identity certificate CSR includes Universally Unique Identifier UUID Common Name CN field following format uuid signing CSR issuing OCF identity certificate PLGD CA verifies authenticity request User OCF Identity Certificate CSR CSR considered user identity CSR Common Name CN matches owner claim provided JSON Web Token JWT derived value it PLGD CA ensures validity JWT proceeding certificate signing process Multiple user identity certificates obtained simultaneously different key pairs Device OCF Identity Certificate CSR CSR s Common Name CN does not meet requirements user identity CSR treated device identity CSR PLGD CA strict policies place prevent unauthorized devices users obtaining identity certificates already signed devices Identity Certificate Management PLGD CA includes comprehensive mechanisms managing lifecycle security identity certificates encompasses issuance renewal deletion identity certificates detailed information manage identity certificates please refer Identity Certificate Management Documentation", + "objectID": "en/docs/services/certificate-authority/certificate-authority", + "description": "What is plgd Certificate Authority?", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Features", + "uri": "en/docs/services/certificate-authority/features", + "content": "Implemented features x2611 OCF Identity Certificate Issuance PLGD Certificate Authority capable issuing OCF identity certificates users devices signing Certificate Signing Requests CSRs x2611 JWT Verification PLGD CA verifies validity JSON Web Tokens JWTs provided CSR ensure authenticity request x2611 Protection Against Unauthorized Identity Certificate Issuance PLGD CA stringent policies place prevent devices users malicious intent obtaining identity certificates already signed devices x2611 HTTP gRPC API PLGD CA provides HTTP gRPC API allowing users interact CA perform certificate related operations x2611 Automatic Deletion Expired Certificates Non identity certificates automatically deleted PLGD CA once expire ensuring secure clutter free certificate infrastructure Planned features x2610 Profiles PLGD CA will introduce concept profiles identity certificates profiles will based owner s information JSON Web Token JWT type certificate device user profiles different configurations settings applied type certificate allowing customization flexibility x2610 Certificate Revocation PLGD CA will implement certificate revocation mechanism will involve maintaining Certificate Revocation List CRL keeps track revoked certificates CA will regularly check validity certificates against CRL ensure compromised invalid certificates promptly revoked no longer considered valid", + "objectID": "en/docs/services/certificate-authority/features", + "description": "What features provides Certificate Authority?", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate", + "features" + ], + "weight": 2 + }, + { + "title": "gRPC API", + "uri": "en/docs/services/certificate-authority/grpc-api", + "content": "", + "objectID": "en/docs/services/certificate-authority/grpc-api", + "description": "Certificate Authority gRPC API", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate" + ], + "weight": 20 + }, + { + "title": "HTTP API", + "uri": "en/docs/services/certificate-authority/http-api", + "content": "", + "objectID": "en/docs/services/certificate-authority/http-api", + "description": "Certificate Authority HTTP API", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate" + ], + "weight": 10 + }, + { + "title": "Identity Certificate Management", + "uri": "en/docs/services/certificate-authority/identity-certificate-management", + "content": "Identity Certificate Management PLGD Certificate Authority CA involves processes mechanisms effectively managing lifecycle security identity certificates issued users devices Issuance Identity Certificates PLGD CA responsible issuing OCF Open Connectivity Foundation identity certificates users devices certificates obtained signing Certificate Signing Requests CSRs submitted entities CA verifies authenticity CSR and validated issues corresponding identity certificate Renewal Expiration Identity certificates validity period expire PLGD CA automatically deletes non device identity certificates once become invalid process ensures expired certificates not clutter system helps maintain secure certificate infrastructure Deletion Identity Certificates Identity certificates deleted using various methods Device Signoff Devices initiate deletion own identity certificates sending signoff requests PLGD CA Device Deletion Hub When device deleted hub using appropriate interface gRPC Gateway API HTTP Gateway API associated identity certificate records deleted Certificate Authority API PLGD CA provides gRPC API HTTP API allow requesting deletion identity certificates deletion mechanisms provide flexibility control management identity certificates ensuring certificates removed needed maintain security integrity detailed information usage instructions please contact us connect plgd dev", + "objectID": "en/docs/services/certificate-authority/identity-certificate-management", + "description": "How to manage certificates?", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate", + "features" + ], + "weight": 30 + }, + { + "title": "CoAP Gateway", + "uri": "en/docs/services/coap-gateway", + "content": "", + "objectID": "en/docs/services/coap-gateway", + "weight": 2 + }, + { + "title": "CoAP API", + "uri": "en/docs/services/coap-gateway/coap-api", + "content": "", + "objectID": "en/docs/services/coap-gateway/coap-api", + "description": "CoAP Gateway API", + "date": "2023-06-14", + "categories": [ + "gateway", + "api" + ], + "keywords": [ + "coap", + "features", + "api" + ], + "weight": 10 + }, + { + "title": "CoAP Gateway", + "uri": "en/docs/services/coap-gateway/coap-gateway", + "content": "CoAP gateway serves server client facilitating communication IoT devices single established connection devices act CoAP servers adhering OCF Open Connectivity Foundation specification IoT devices primary functions CoAP gateway authentication authorization devices access cloud services Authentication based certificates authorization relies JWT JSON Web Token tokens Authentication Devices connecting CoAP gateway verify its certificates CoAP gateway offers three authentication methods OCF Identity Certificate Devices authenticated using OCF identity certificate issued PLGD Certificate Authority option enforces validation JWT token containing claim device ID involves mutual TLS Transport Layer Security connection CoAP gateway verifies device certificate Certificate Devices use certificate authentication including manufacturer certificates Similar previous method requires mutual TLS connection does not check certificate OCF identity certificate Disable Authentication devices allowed connect IoT hub without authentication option similar accessing bank account considered TLS connection authentication CoAP gateway proceeds authorize device s access IoT hub JWT token Authorization Authorization essential enabling communication IoT hub CoAP gateway authorizes devices access IoT hub using JWT token two ways CoAP gateway perform authorization Valid Token Device ID Claim token contain claim device ID successful authorization Valid Token Only Authorization granted based solely validity token authorization tied connection meaning device gets disconnected authorized again command sent device IoT hub associated device s JWT token Synchronize Device Twin Once device authentication completed synchronization device twin begins device publishes resources CoAP gateway subscribes resources forwarding changes IoT hub update device twin Process Events Device During device twin synchronization CoAP gateway subscribes events IoT hub translates CoAP commands sent devices event awaiting device s online status CoAP gateway immediately sends device", + "objectID": "en/docs/services/coap-gateway/coap-gateway", + "description": "What is plgd CoAP Gateway?", + "date": "2023-06-16", + "categories": [ + "gateway", + "iot" + ], + "keywords": [ + "coap", + "iot" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Features", + "uri": "en/docs/services/coap-gateway/features", + "content": "Implemented Features x2611 Server Client Functionality CoAP gateway acts server client facilitating communication IoT devices single connection x2611 OCF Specification Compliance CoAP gateway adheres OCF specification IoT devices ensuring compatibility interoperability OCF compliant devices x2611 Device Authentication CoAP gateway supports multiple authentication methods including OCF identity certificate certificate disable authentication providing flexibility verifying device credentials x2611 Device Authorization Devices authorized access IoT hub based JWT token provided either requiring device ID claim validating overall token s validity x2611 Device Twin Synchronization authentication CoAP gateway synchronizes device twin subscribing device resources forwarding changes IoT hub ensuring accurate representation device s state x2611 Event Processing CoAP gateway subscribes events IoT hub converts CoAP commands allowing seamless communication devices during device twin synchronization process x2611 Time Resource CoAP gateway provides current time authenticated devices allowing synchronize internal clocks x2611 Device Twin Synchronization ETAG Implementing ETAG mechanism will ensure device twin synchronization occurs when device s state changed last synchronization optimization reduces unnecessary data transfer CoAP gateway IoT hub enhancing performance when device online x2611 Monitoring Device Connectivity Monitors device connectivity status determine device online offline Planned Features x2610 Device Logging Introduce device logging capabilities record detailed activity logs device logs forwarded Open Telemetry collector further analysis monitoring purposes x2610 OpenTelemetry Metrics CoAP gateway will incorporate OpenTelemetry metrics providing detailed insights gateway s performance resource utilization feature will allow comprehensive monitoring analysis gateway s behavior", + "objectID": "en/docs/services/coap-gateway/features", + "description": "What features provides CoAP Gateway?", + "date": "2023-06-14", + "categories": [ + "gateway", + "iot" + ], + "keywords": [ + "api", + "coap", + "features" + ], + "weight": 2 + }, + { + "title": "Device Provisioning Service", + "uri": "en/docs/services/device-provisioning-service", + "content": "", + "objectID": "en/docs/services/device-provisioning-service", + "weight": 1 + }, + { + "title": "Attestation Mechanisms", + "uri": "en/docs/services/device-provisioning-service/attestation-mechanisms", + "content": "important part zero touch provisioning attestation mechanism method used confirm device s identity enrollment group needs attestation mechanism configured Selected method it s configuration used identify enrollment group device opening connection DPS belongs to Device Provisioning Service supports 2 forms attestations Manufacturer certificates based standard X 509 certificate authentication flow Trusted Platform Module TPM based nonce challenge X 509 Certificates Digital certificates allow individuals organizations devices establish trust digital world foundation digital identities X 509 certificates everywhere essential every connected process websites applications devices online documents level trust established X 509 certificates work issued key usage architecture lets certificates verify that public key belongs hostname domain organization individual contained within certificate signed trusted issuer Certificate Authority CA When certificate signed trusted CA certificate user confident certificate owner validated using X 509 certificate attestation mechanism device s manufacturer certificate used verify it s identity certificate typically arranged certificate chain trust certificate chain signed private key next higher certificate arrangement establishes delegated chain trust CA certificate down intermediate CA manufacturer end identity leaf certificate installed device certificate chain trust built usually reflected physical logical hierarchy devices products example device manufacturer may Issue single self signed root CA certificate Use root CA certificate sign per factory issued intermediate CA Use factory s intermediate CA sign per production line issued intermediate CA Use production line intermediate CA sign end identity manufacturer certificate installed device govern issuance digital certificates scalable way public key infrastructure PKI required Manufacturer certificate manufacturer certificate leaf certificate signed manufacturer s root intermediate CA uniquely identifies device certificate used during provisioning process verify device manufactured particular company device connecting DPS needs authenticate using client certificate during DPS verifies it s public key against root CA intermediate CA registered matching enrollment group device present leaf certificate certificate chain leaf certificate certificate verified proof of possession otherwise authentication will fail Successful verification public key results successfully connected device developed declared manufacturer eligible provisioning Verification DPS server certificate device configurable learn more DPS Client API Successfully provisioned device switches using Manufacturer certificate Identity certificates communication plgd hub devices network when connecting DPS service again uniquely identify device it s recommended set certificate common name CN unique product identifier e g serial number allows whitelist blacklist devices what s configurable enrollment group level know feature Whitelisting BlackListing Certificate chain trust certificate chain list certificates followed one CA certificates RFC 5280 certificate chain chain trust defined certification path words chain trust refers certificate linked back trusted Certificate Authority order certificate trusted traceable back trust root signed off meaning certificates chain server intermediate root need properly trusted three parts chain trust Root Certificate digital certificate belongs issuing Certificate Authority root certificates closely guarded CAs Intermediate Certificate branch off root certificates branches trees act middle men protected root certificates manufacturer certificates issued devices Manufacturer certificate end entity certificate one issued specific device system needing coverage for Certificate chains used order check public key data contained end entity certificate the first certificate chain effectively belong its subject order ascertain this signature end target certificate verified using public key contained following certificate whose signature verified using next certificate so until last certificate chain reached last certificate trust anchor successfully reaching will prove end entity certificate trusted Certificate chain authentication scenarios Part enrollment group configuration certificate chain used authentication enrollment group selection device authenticating against DPS required provide certificate chain end entity certificate leaf most certificate present certificate chain configured enrollment group Otherwise authentication will fail example consider manufacturer uses following certificate chain device sends following manufacturer certificate chain certificate chain configured enrollment group looks like authentication fails DPS can t attempt authentication assuming validity Intermediate CA 2 device authenticates using manufacturer certificate chain containing certificates Intermediate CA 2 certificate chain configur", + "objectID": "en/docs/services/device-provisioning-service/attestation-mechanisms", + "description": "How is the device identity confirmed?", + "date": "2022-02-15", + "categories": [ + "zero-touch", + "provisioning" + ], + "keywords": [ + "attestation", + "x509", + "TPM", + "manufacturer-certificate" + ], + "weight": 3 + }, + { + "title": "Client Library", + "uri": "en/docs/services/device-provisioning-service/client-library", + "content": "Package interested testing zero touch provisioning Reach us Device Provisioning Service distributed tar gz package contains dps shared library public C headers example application Please examine contents provided pkg config pc file install required dependencies DPS Client API API defined public header files provided distributed package dps h dps_export h dps_log h Initialize DPS DPS client device extension IoTivity device Define desired device add DPS code automatically provision device Start DPS initialization calling plgddpsinit function allocates initializes required data structures Use setters plgddpssetendpoint plgddpssetmanagercallbacks plgddpssetskipverify plgddpssetconfigurationresource plgddpstimeconfigure plgddpssetretryconfiguration plgddpssetcloudobserverconfiguration plgddpspkisetexpiringlimit configure device Set DPS Endpoint set DPS endpoint call plgddpssetendpoint plgddpscontextt ctx const char endpoint function Set status callbacks DPS client device optionally provide two custom callbacks track provisioning status cloud registration status calling plgddpssetmanagercallbacks function status cloud registration part public API IoTivity examined there DPS status callback executed whenever provisioning step succeeds fails callback following signature void struct plgddpscontextt ctx plgddpsstatust status void data ctx argument device context created plgddpsinit data argument value provided call plgddpssetmanagercallbacks status argument integer value consists following flags defined dps h header brief DPS provisioning status flags typedef enum PLGDDPSINITIALIZED 1 verification DPS disabled calling plgddpssetskipverify false Provisioning Provisioning algorithm asynchronous consists several steps step finishes schedules next step whole process fired calling plgddpsmanager_start provisioning successfully finished connection DPS endpoint closed registration plgd hub started using data set during provisioning Handling failure step provisioning algorithm encounters error does not trigger next step for example answer DPS endpoint didn t come thus handler didn t trigger schedule next step step retried small interval application uses following retry intervals 10s 20s 40s 80s 120s forever loops array i e when last retry interval 120s next will 10s again until provisioning process succeeds read retry mechanism DPS Client Library read here Time synchronization order TLS handshake verify server certificate certificate rotation occur device correct time Time synchronization achieved utilizing DPS clients synchronize DPS server enable time synchronization function plgddpstimeconfigure true called It s important note IoTivity Lite needs compiled cmake option DPLGDDEVTIMEENABLED ON order enable time synchronization feature IoTivity Lite library initialized plgdtimeinit compensate disabled time verification during TLS handshake time synchronization established separate connection Once synchronization completed connection terminated device s time adjusted bring back alignment approach may not provide pinpoint accuracy adequate verifying server certificate during TLS handshake certificate rotation precise time synchronization utilizing NTP time synchronization protocol recommended Certificate renewal Proper device functionality contingent upon time synchronization certificate retrieved DPS service one following states not yet valid valid from time hasn t yet passed expired valid to time passed already expiring valid to time will pass soon the expiration interval determined expiringLimit value default 1 hour valid otherwise provisioning credentials step retrieved certificates checked validity least one retrieved certificates not valid discarded whole step repeated valid certificate fulfills following conditions certificate correctly parsed stored IoTivity lite library its valid from valid to timestamps currently valid certificate not expiring ie interval until certificate expires longer expiringLimit value Once certificates stored certificate renewal operation scheduled based earliest valid to timestamp retrieved certificate Setting expiration interval set expiration interval use plgddpspkisetexpiringlimit current expiration interval call plgddpspkigetexpiringlimit interval seconds default value 1 hour 3600 seconds Certificate renewal interval interval certificate renewal operation scheduled retrieved certificates examined minimal valid to timestamp minvalidto found internal calculated following simple algorithm certificate expiring minvalidto within 1 minute now return 0 force renewal trigger right away minvalidto within 3 minutes return 1 minute minvalidto within 6 minutes return 2 minutes return 2 3 remaining time until minvalidto passed Replacing certificates Once renewal interval reached certificate renewal operation executed certificate signing request CSR sent DPS service When response new certificates received new certificates ", + "objectID": "en/docs/services/device-provisioning-service/client-library", + "description": "How to create a client of plgd Device Provisioning Service?", + "date": "2023-04-19", + "categories": [ + "zero-touch", + "provisioning" + ], + "keywords": [ + "provisioning" + ], + "weight": 2 + }, + { + "title": "Device Provisioning Service", + "uri": "en/docs/services/device-provisioning-service/device-provisioning-service", + "content": "Provisioning millions devices secure scalable manner without requiring human interaction plgd Device Provisioning Service DPS solves Doesn t matter you re running plgd hub on premise off premise fully managed instance DPS makes sure trusts devices provision right plgd hub instance Exactly no human interaction zero touch provision pre configure millions devices just in time securely using manufacturer certificates TPMs When use Device Provisioning Service plgd ecosystem supports various provisioning scenarios including Zero touch provisioning handled DPS It s perfect choice when try solve Provision huge number devices without hard coding plgd hub connection Distribute devices across different plgd hub instances based custom identifier e g serial number Distribute devices customer specific environments securing communication using customer s custom certificate Distribute devices based use case support solution isolation use cases Drive custom ACL Identity Certificate devices based security requirements use cases Reprovision device when not able connect plgd hub Blacklist devices compromised discontinued Certificate rotation Provisioning process Securely provisioned device DPS precedes 3 distinct steps manufacturing step device prepared factory operation setup step DPS configured automated provisioning provisioning step device enrolled it s manufacturer identity verified Manufacturing step successfully attest device s identity during provisioning process manufacturer certificate or and TPM need available device It s key verify device trusted belongs enrollment group created DPS Creation device s manufacturer identity usually occurs towards end manufacturing process point hardware assembly complete initial software loaded manufacturing PC connected device requests PKI unique manufacturer certificate using unique device identifier e g serial number depends manufacturer case device contains TPM manufacturing PC stores TPM s endorsement key required it s individual enrollment Process described above varies manufacturer manufacturer Nevertheless unique device s manufacturer identity expected result Additionally formulation Creation device s manufacturer identity used not confuse reader using accurate term Provisioning device s manufacturer identity DPS does not introduce new step manufacturing process ties existing step creating unique identifying key information device s manufacturer certificate TPM s endorsement key used device attestation during zero touch provisioning DPS Operation setup step Creating Enrollment Group plgd DPS instance required order sure DPS properly attest device s identity when comes looking its provisioning configuration operator responsible include identifying key information described manufacturer step add enrollment group Part enrollment group configuration among others initial resource ACL configuration useful device to device scenarios plgd hub not involved all Once enrollment group configured DPS ready automatically provision devices Unless use case list devices changes DPS service enrollment group does not modified Number enrollment groups not limited different set devices attested different enrollment groups containing different provisioning configuration Provisioning step Enrollment Group created during operation setup state set required optional configuration options supporting various use cases security requirements following sequence diagram describes goes hood device securely provisioned flow dependent Enrollment Group configuration prerequisite startuml skinparam backgroundColor grey hide footbox actor Solution Operator op collections Devices d participant Device Provisioning nService dps participant plgd hub hub note op hub Enrollment Entry including Devices key identifiers created end note d d 1 Initiate device ownership transfer activate d d dps 2 Connect authenticate dps dps 3 Find matching Enrollment Group activate dps d dps 4 DPS service time sync clocks dps d d dps 5 owner device dps d d dps 6 Send Identity Certificate Signing Request dps d d dps 7 Retrieve ACL configuration dps d d dps 8 initial configuration dps d d dps 9 plgd hub connection configuration dps d d x dps Disconnect deactivate dps deactivate d d hub 10 Connect authenticate activate d enduml device application external tool discovered device using CoAP multicast requests DPS Client start provisioning process setting DPS endpoint DPS endpoint configured factory device opens connection DPS proves it s identity using Manufacturer Certificate TPM s endorsement key DPS finds Enrollment Group matching Manufacturer Certificate CA TPM s endorsement key order validate TLS certificates rotate them device synchronizes its clock DPS obtaining current time device s owner granted access DPS enabling device operate Device to Device scenarios device issues Certificate Signing Request CSR unique device Identity requests DPS sign it CSR signed separate service r", + "objectID": "en/docs/services/device-provisioning-service/device-provisioning-service", + "description": "What is plgd Device Provisioning Service?", + "date": "2022-01-26", + "categories": [ + "zero-touch", + "provisioning" + ], + "keywords": [ + "provisioning", + "TPM", + "manufacturer-certificate" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Features", + "uri": "en/docs/services/device-provisioning-service/features", + "content": "Implemented features x2611 Device attestation via certificates feature allows devices prove identity using certificates x2611 Onboarding devices plgd hub feature enables process adding devices management control plgd hub x2611 Control provisioned device local network feature users access provisioned devices directly local network enabling perform maintenance tasks manage devices conveniently x2611 Synchronize device time Device Provisioning Service feature ensures devices synchronized time Device Provisioning Service x2611 Rotate device certificates feature allows rotation device certificates enhancing security maintaining up to date certificates x2611 HTTP API configure access devices feature provides HTTP API allows users configure enrollment groups x2611 HTTP API provisioned configuration devices feature offers HTTP API retrieve provisioned configurations devices Planned features x2610 Device attestation via TPM upcoming feature will enable devices attest identity using Trusted Platform Modules TPM x2610 Initial device configuration planned feature aims provide users mechanism perform initial configuration devices during provisioning process x2610 Blacklisting whitelisting devices feature users will ability blacklist whitelist specific devices enhanced access control x2610 Manual approval device configuration planned feature enables mechanism devices require manual approval user order receive configuration settings Instead automatic configuration users will control granting permission device configuration", + "objectID": "en/docs/services/device-provisioning-service/features", + "description": "What features provides Device Provisioning Service?", + "date": "2023-05-19", + "categories": [ + "zero-touch", + "provisioning" + ], + "keywords": [ + "provisioning", + "TPM", + "manufacturer-certificate" + ], + "weight": 2 + }, + { + "title": "Starting zero-touch provisioning", + "uri": "en/docs/services/device-provisioning-service/onboarding-device", + "content": "IoTivity devices extended Device Provisioning Client library enables use zero touch provisioning feature Integrating library device enables start automated provisioning 2 APIs DPS Client Library API DPS Client library Configuring DPS resource DPS Client Library API Provisioning process initiated application immediately when device started managed device firmware without external interaction read interact configure DPS Client Library read here DPS Resource DPS resource enabled using DPS Client Library API users deamons possibility trigger automated provisioning configuring resource network configure DPS endpoint resource device needs self provisioning owned onboarding tool resource observed published plgd hub enables track provisioning progress observing value ps property configure DPS Resource trigger device provisioning owned devices need update DPS resource endpoint dps coaps tcp try plgd cloud 25684 err c UpdateResource ctx deviceID plgd dps map string interface endpoint dps nil err nil panic err that device provisioning client will provision configuration ACLs cloud configuration DPS onboard device plgd hub Setup DPS trust anchor device device default verifies endpoint certificate trust anchors installed using C API ocpkiaddmfgtrust_anchor provisioning certificate onboarding tool set trust anchors change operation mode normal provisioning update credential resource return normal operation mode trustAnchor BEGIN CERTIFICATE n n END CERTIFICATE n d links err c GetRefDevice ctx deviceID err nil panic err defer d Release ctx change operation mode normal provisioning p err d Provision ctx links err nil panic err update credential resource err p AddCredentials Credentials credential Credential Subject uuid NewSHA1 uuid NameSpaceDNS byte try plgd cloud String Type credential CredentialTypeASYMMETRICSIGNINGWITHCERTIFICATE Usage credential CredentialUsageMFGTRUST_CA PublicData credential CredentialPublicData DataInternal trustAnchor Encoding credential CredentialPublicDataEncoding_PEM return normal operation mode errPro p Close ctx err nil panic err errPro nil panic err", + "objectID": "en/docs/services/device-provisioning-service/onboarding-device", + "description": "What are the possibilites on triggering the zero-touch provisioning?", + "date": "2022-06-20", + "docsOthersDisplay": true, + "categories": [ + "zero-touch", + "provisioning" + ], + "keywords": [ + "provisioning", + "dps" + ], + "weight": 4 + }, + { + "title": "Retry mechanism", + "uri": "en/docs/services/device-provisioning-service/retry-mechanism", + "content": "Various failures occur DPS device running failures recoverable handled retrying failed step triggering full reprovisioning mechanism illustrated following diagram used retry interval determined retry counter retry configuration Internally DPS client library uses counter keep track number retries timeouts Configuration retry configuration consists array non zero values interpreted retry intervals seconds maximal size configuration array 8 default retry configuration initialized following array values 10 20 40 80 120 configuration changed plgddpssetretryconfiguration function retrieve current configuration use plgsdpsgetretryconfiguration function Failures during provisioning Provisioning consists 3 main steps sending signing certificate request requesting applying ACLs requesting applying plgd hub connection configuration step sends request DPS service waits response request sent retry interval used deadline response not received deadline operation timeouts request resend response received time its status code checked distinguish transient non transient errors Non transient errors force full provisioning retry Transient errors first try repeat failed step case problem clears up However transient failure occurs consecutively 3 times full reprovisioning forced retry counter starts zero retry either transient non transient error timeout increments retry counter counter reset zero provisioning step successfully finishes value retry counter greater maximal index configuration array counter reset back zero Failures cloud manager connection authentication successful provisioning device disconnects DPS service starts cloud manager IoTivity lite cloud manager fails start full reprovisioning triggered cloud manager starts successfully cloud status observer starts operate Cloud status observer simple polling mechanism examines cloud status value 30 times 1 second intervals observer checks cloud status waits status OCCLOUDREGISTERED OCCLOUDLOGGED_IN flags sets flags set polling stops limit polling checks reached flags not set cloud manager stopped full reprovisioning forced polling mechanism restarted soon connection plgd hub lost limit polling checks default 30 interval default 1 second configured plgddpssetcloudobserver_configuration function Valid authentication cloud manager depends valid access token access token retrieved during provisioning not permanent will eventually expire refreshed otherwise plgd hub will close connection device handled internally IoTivity lite library schedules refresh token operation access token expires", + "objectID": "en/docs/services/device-provisioning-service/retry-mechanism", + "description": "How is recoverable failure handled?", + "date": "2022-06-28", + "categories": [ + "zero-touch", + "provisioning" + ], + "keywords": [ + "retry", + "recovery", + "failure" + ], + "weight": 5 + }, + { + "title": "Zero Touch Provisioning via DHCP", + "uri": "en/docs/services/device-provisioning-service/sztp-via-dhcp", + "content": "DHCP based zero touch provisioning method configuring devices using DHCP protocol automatically assigning IP addresses devices network article explains configure zero touch provisioning via DHCP Overview When provisioning device needs configured endpoint and necessary TLS settings three options securing TLS connection device DPS service 1 Use Root Certificate Authority mTLS manufacturer preinstalls root certificate authority CA certificate DPS service device During firmware updates certificates updated DPS service needs leaf certificate signed root preinstalled CA certificate obtain certificate manufacturer s customer needs use certificate signing request CSR sign intermediate certificate authority leaf certificate manufacturer provides intermediate certificate authority customer sign intermediate CA leaf certificate limit sub intermediate CA pathLenConstraint field used 0 means intermediate CA create leaf certificate When device establishes TLS connection DPS service intermediate CA certificates provided chain device contains root CA certificate manufacturer responsible updating root CA certificate device via firmware update providing new intermediate CA leaf certificate customer rotation root CA certificate device implementation point view root certificate authority CA certificates stored directory them read certificate add trusted manufacturer certificate store iotivity lite using ocpkiaddmfgtrust_anchor during device initialization 2 Use Fingerprint Certificate mTLS device connected network untrustworthy DHCP server using fingerprint verify DPS certificate does not provide security scenario using skip certificate verification However root certificate authority via DHCP large Therefore user provide fingerprint certificate chain message digest used e g SHA256 SHA384 case device configured fingerprint DPS certificate unique identifier computed certificate fingerprint used verify DPS certificate DPS chain contain one certificate fingerprint configured via DHCP message digest type used calculate fingerprint configured DHCP server so device obtain necessary configuration parameters during provisioning Additionally device configured allow use configured message digest algorithm 3 Use Skip Certificate Verification TLS simplest configure device intruder steal device when connected network untrusted DHCP server replace DPS endpoint intruder s server When using Skip Certificate Verification TLS option device trusts certificates sent DPS service DPS service verifies device s certificate during TLS handshake option used when device connected trusted network untrusted network allow attacker steal device replace DPS endpoint own server want skip certificate verification DPS service set skipverify parameter true using plgddpssetskip_verify function details function found dps h configure Zero Touch Provisioning via DHCP Configuring kea dhcp server configure kea dhcp server provide zero touch provisioning via DHCP modify etc kea kea dhcp4 conf file include following lines Dhcp4 interfaces config interfaces eth0 network interfaces want provide DHCP option data space dhcp4 name domain name code 15 data example org domain name space dhcp4 name domain name servers code 6 data 8 8 8 8 DNS server space dhcp4 name ntp servers code 42 data 213 81 129 99 NTP server option def space MY COMPANY name dps endpoint endpoint DPS service code 200 type string space MY COMPANY name dps certificate fingerprint fingerprint DPS certificate chain code 201 type binary space MY COMPANY name dps certificate fingerprint md type message digest type used calculate fingerprint code 202 type string client classes name MY COMPANY CLASS match substring vendor class identifier option test substring option 60 hex 0 10 MY COMPANY DEVICE option def name vendor encapsulated options code 43 type empty encapsulate MY COMPANY option data name vendor encapsulated options code 43 space MY COMPANY name dps endpoint data coaps tcp dps mycompany com 5684 space MY COMPANY name dps certificate fingerprint data A1E1C34C3E03178DE47779F992287DFEB4B7702F80EED915DDECD654E4C64FE2 space MY COMPANY name dps certificate fingerprint md type data SHA256 subnet4 id 1 subnet 10 115 115 0 24 pools pool 10 115 115 100 10 115 115 200 option data space dhcp4 name routers code 3 data 10 115 115 10 host reservation identifiers hw address reservation mode global reservations set static ip hostname test hw address 08 00 27 49 cb b2 ip address 10 115 115 11 dps certificate fingerprint optional use 2 option refers certi", + "objectID": "en/docs/services/device-provisioning-service/sztp-via-dhcp", + "description": "How is configured Zero Touch Provisioning via DHCP?", + "date": "2023-03-03", + "categories": [ + "zero-touch", + "provisioning", + "dhcp" + ], + "keywords": [ + "dhcp", + "provisioning" + ], + "weight": 5 + }, + { + "title": "Time Synchronization", + "uri": "en/docs/services/device-provisioning-service/time-synchronization", + "content": "When device experiences disruption power supply during power outage when device s motherboard clock battery fails time device become unsynchronized Similarly battery device runs power time become desynchronized seemingly small issue cause significant problems especially secure devices rely TLS certificates verification TLS certificates crucial element secure communication used establish trust two parties During verification process validity certificate checked including time issued time expires device s time incorrect verification process will fail so won t trust service certificate far future opposite Thus ensuring time device accurate utmost importance maintaining security integrity secure communication channels prevent potential problems essential device capable synchronizing its time external source utilizing external time source device accurately set its time perform verification TLS certificates multiple methods synchronizing time device including NTP GPS dedicated time server Nevertheless prevalent approach synchronizing time device involves using time server provided cloud platform event device unable establish connectivity external time source use last synchronized time rough approximation current time Synchronization time device provisioning service feature enabled device s time unsynchronized device will synchronize its time hub first step initialization process time synchronization performed sending CoAP request x plgd dev time resource service sent secure connection undergoes TLS certificate verification During time synchronization process device will accept hub certificate even either valid future already expired occurs device will terminate connection completing time synchronization resume its operations normal worth noting enabling time synchronization feature IoTivity lite requires additional step during configuration CMake Specifically done adding cmake DPLGDDEVTIMEENABLED ON DOCCLOUD_ENABLED ON command enable feature IoTivity Lite Time IoTivity Lite provides resource used synchronize time device allow feature need compile IoTivity lite cmake DPLGDDEVTIME_ENABLED ON When set time device will store time persistent storage will restored device restart So device time past during initialization time persistent storage will used current time multiple devices iotivity lite time resource will shared among them definition time resource available swagger interested using feature Docker container note already enabled cloud_server Docker image run image specific time example January 1st 2000 11 12 13 use following command docker run rm it pull always e FAKETIME 2000 01 01 11 12 13 ghcr io iotivity iotivity lite cloud server discovery resource observable master Calculating current time order calculate current time utilize monotonic time system conjunction last synchronized time Monotonic time represents time continuously increasing starting point typically system boot time not affected changes system clock otherwise affect system time current time computed adding elapsed time synchronization lastSyncTime Upon setting lastSyncTime system s monotonic time recorded When determining elapsed time simply calculate difference monotonic time synchronization current monotonic time time query current time elapsed time monotonic time monotonic time synchronization current time lastSyncTime elapsed time C API When initializing time feature via plgdtimeinit function C API several parameters set include specifying whether use time MbedTLS time callback TLS certificate verification specifying callback function set device clock information parameters functions C API set get time please refer doxygen documentation example implement feature please refer cloud_server c file iotivity lite repository", + "objectID": "en/docs/services/device-provisioning-service/time-synchronization", + "description": "How to synchronize time on the device?", + "date": "2023-03-20", + "categories": [ + "features" + ], + "keywords": [ + "time-synchronization", + "iotivity-lite", + "provisioning", + "zero-touch", + "TLS", + "NTP", + "GPS", + "time server" + ], + "weight": 100 + }, + { + "title": "gRPC Gateway", + "uri": "en/docs/services/grpc-gateway", + "content": "", + "objectID": "en/docs/services/grpc-gateway", + "weight": 3 + }, + { + "title": "Features", + "uri": "en/docs/services/grpc-gateway/features", + "content": "Implemented Features x2611 Device Management gRPC Gateway provides comprehensive device management capabilities including retrieving devices deleting devices managing resource links accessing specific resources retrieving device twin information updating resources deleting resources creating resources x2611 Event Handling Subscription Clients subscribe device events retrieve events based device ID resource ID event types x2611 Device Metadata Configuration gRPC Gateway allows retrieval hub configuration updating device metadata e g device twin retrieving devices metadata including online offline status device twin synchronization canceling pending metadata updates x2611 Command Handling gRPC Gateway enables retrieval pending commands devices cancellation resource commands x2611 Protocol Buffers Protobuf Support gRPC Gateway utilizes Protocol Buffers defining service interfaces message structures enabling efficient language agnostic communication Planned Features x2610 Metrics gRPC Gateway will provide metrics monitoring capabilities allowing visibility its performance resource utilization operational insights", + "objectID": "en/docs/services/grpc-gateway/features", + "description": "What features provides gRPC Gateway?", + "date": "2023-06-14", + "categories": [ + "gateway", + "client" + ], + "keywords": [ + "api", + "grpc", + "features" + ], + "weight": 2 + }, + { + "title": "gRPC API", + "uri": "en/docs/services/grpc-gateway/grpc-api", + "content": "", + "objectID": "en/docs/services/grpc-gateway/grpc-api", + "description": "gRPC Gateway API", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate" + ], + "weight": 20 + }, + { + "title": "gRPC Gateway", + "uri": "en/docs/services/grpc-gateway/grpc-gateway", + "content": "gRPC Gateway integral component empowers control devices control plane using gRPC Google Remote Procedure Call protocol Here s overview functionalities provided gRPC Gateway Device Management GetDevices Retrieves list devices DeleteDevices Deletes selected devices GetResourceLinks Retrieves resource links devices GetResourceFromDevice Retrieves specific resource device GetResources Retrieves resources device twin UpdateResource Updates resource device DeleteResource Deletes resource device CreateResource Creates resource device Event Handling Subscription SubscribeToEvents Subscribes events related devices GetEvents Retrieves events given combination device ID resource ID timestamp Device Metadata Configuration GetHubConfiguration Retrieves hub configuration UpdateDeviceMetadata Enables disables device twin GetDevicesMetadata Retrieves metadata devices including online offline status device twin status CancelPendingMetadataUpdates Cancels pending device metadata updates Command Handling GetPendingCommands Retrieves pending commands devices CancelPendingCommands Cancels resource commands detailed information please refer gRPC Gateway API documentation", + "objectID": "en/docs/services/grpc-gateway/grpc-gateway", + "description": "What is plgd gRPC Gateway?", + "date": "2023-06-16", + "categories": [ + "gateway", + "iot" + ], + "keywords": [ + "grpc", + "iot" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "HTTP Gateway", + "uri": "en/docs/services/http-gateway", + "content": "", + "objectID": "en/docs/services/http-gateway", + "weight": 4 + }, + { + "title": "Features", + "uri": "en/docs/services/http-gateway/features", + "content": "Implemented Features x2611 HTTP WebSocket Functionality HTTP Gateway equipped HTTP server WebSocket server facilitating seamless communication devices using protocols x2611 gRPC Gateway API Integration operations within HTTP Gateway seamlessly integrated gRPC Gateway API ensuring compatibility streamlined interaction experience devices x2611 Device Management HTTP Gateway provides extensive device management capabilities including retrieving device information deleting devices managing resource links accessing specific resources retrieving device twin information updating deleting resources creating new resources x2611 Event Handling Subscription Clients ability subscribe events related devices HTTP Gateway allows retrieval events based device ID resource ID event types x2611 Device Metadata Configuration HTTP Gateway offers functionalities retrieving hub configuration updating device metadata such device twin retrieving devices metadata including online offline status device twin synchronization canceling pending metadata updates x2611 Command Handling HTTP Gateway facilitates retrieval pending commands devices enables cancellation device resource device commands Planned Features x2610 Metrics HTTP Gateway will provide metrics monitoring capabilities allowing visibility its performance resource utilization operational insights", + "objectID": "en/docs/services/http-gateway/features", + "description": "What features provides HTTP Gateway?", + "date": "2023-06-14", + "categories": [ + "gateway", + "client" + ], + "keywords": [ + "api", + "http", + "features" + ], + "weight": 2 + }, + { + "title": "HTTP API", + "uri": "en/docs/services/http-gateway/http-api", + "content": "", + "objectID": "en/docs/services/http-gateway/http-api", + "description": "HTTP Gateway API", + "date": "2023-06-14", + "categories": [ + "certificate" + ], + "keywords": [ + "identity-certificate", + "certificate" + ], + "weight": 10 + }, + { + "title": "HTTP Gateway", + "uri": "en/docs/services/http-gateway/http-gateway", + "content": "HTTP Gateway crucial component facilitates control devices control plane utilizing HTTP WebSocket protocols serves interface managing various operations seamlessly integrated gRPC Gateway API Here s overview functionalities provided HTTP Gateway Device Management GetDevices Retrieves list devices DeleteDevices Deletes selected devices GetResourceLinks Retrieves resource links devices GetResourceFromDevice Retrieves specific resource device GetResources Retrieves resources device twin UpdateResource Updates resource device DeleteResource Deletes resource device CreateResource Creates resource device Event Handling Subscription via WebSocket SubscribeToEvents Subscribes events associated devices GetEvents Retrieves events given combination device ID resource ID timestamp Device Metadata Configuration GetHubConfiguration Retrieves hub configuration UpdateDeviceMetadata Enables disables device twin GetDevicesMetadata Retrieves metadata devices including online offline status device twin status CancelPendingMetadataUpdates Cancels pending device metadata updates Command Handling GetPendingCommands Retrieves pending commands devices CancelPendingCommands Cancels resource commands detailed information refer HTTP Gateway API documentation Additionally specific details integration gRPC Gateway API found here", + "objectID": "en/docs/services/http-gateway/http-gateway", + "description": "What is plgd HTTP Gateway?", + "date": "2023-06-16", + "categories": [ + "gateway", + "iot" + ], + "keywords": [ + "http", + "iot" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Identity store", + "uri": "en/docs/services/identity-store", + "content": "", + "objectID": "en/docs/services/identity-store", + "weight": 8 + }, + { + "title": "Features", + "uri": "en/docs/services/identity-store/features", + "content": "Implemented Features x2611 Device Owner Relationship Management Identity Store efficiently manages association devices owners within Hub x2611 Device Registration Devices registered Hub indicating assignment owner Identity Store x2611 Device Unregistration Devices unregistered Hub signifying disassociation owner Identity Store x2611 Event Propagation Changes Identity Store device registrations unregistrations propagated Hub DevicesRegistered DevicesUnregistered events x2611 Customizable Owner Claim Name Identity Store offers flexibility customize name owner claim allowing personalized owner identification x2611 Hub Identification Events Add hub ID events enable identification hub generated event Planned Features x2610 Device Sharing among Owners Enable devices shared among multiple owners expanding collaboration access capabilities devices within Identity Store", + "objectID": "en/docs/services/identity-store/features", + "description": "What features provides Identity Store?", + "date": "2023-06-14", + "categories": [ + "ownership", + "iot" + ], + "keywords": [ + "owner", + "validation", + "features" + ], + "weight": 2 + }, + { + "title": "Identity Store", + "uri": "en/docs/services/identity-store/identity-store", + "content": "Identity Store serves repository maintaining relationship devices owners When device registered Hub indicates device assigned specific owner Identity Store Conversely when device unregistered Hub means device no longer associated owner Identity Store essence Identity Store functions means manage ownership devices within Hub ensure synchronization modifications made Identity Store communicated Hub two events DevicesRegistered DevicesUnregistered events serve mechanisms propagating changes Identity Store Hub ensuring device ownership accurately reflected across system", + "objectID": "en/docs/services/identity-store/identity-store", + "description": "What is plgd Identity Store?", + "date": "2023-06-16", + "categories": [ + "storage" + ], + "keywords": [ + "users", + "owners" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Resource Aggregate", + "uri": "en/docs/services/resource-aggregate", + "content": "", + "objectID": "en/docs/services/resource-aggregate", + "weight": 5 + }, + { + "title": "Features", + "uri": "en/docs/services/resource-aggregate/features", + "content": "Implemented Features x2611 Event driven Transaction Handling Resource Aggregate operates based fine grained event streams enabling transactional operations device s resource x2611 Event Persistence Events describing actions within Resource Aggregate persisted EventStore creating append only log resource s state changes x2611 Event Deduplication Resource Aggregate deduplicates events prevent duplicate events emitted when command arrives x2611 Event Publication Persisted events EventStore published EventBus distribution system components services interested resource related events x2611 Optimistic Concurrency Control Resource Aggregate utilizes optimistic concurrency control method prevent conflicts during writes EventStore x2611 Snapshot based State Optimization Implementing snapshot functionality capture store periodic snapshots resource s state enhancing performance reducing need event replay during recovery processes x2611 Command Validation Incoming commands Resource Aggregate validated ensure correctness adherence defined rules x2611 Command Expiration command valid until time requires confirmation event confirmation event not received valid until time pending command considered invalid discarded x2611 Cancel Commands Resource Aggregate supports cancellation pending commands allowing gateway cancel command not yet processed Resource Aggregate x2611 Pending Command Execution Device Online Commands awaiting device s online status immediately processed when device comes online x2611 Hub Identification Events Add hub ID events enable identification hub generated event", + "objectID": "en/docs/services/resource-aggregate/features", + "description": "What features provides Resource Aggregate?", + "date": "2023-06-14", + "categories": [ + "events", + "iot" + ], + "keywords": [ + "cqrs", + "features" + ], + "weight": 2 + }, + { + "title": "Resource Aggregate", + "uri": "en/docs/services/resource-aggregate/resource-aggregate", + "content": "Resource Aggregate fundamental concept plgd scopes every transaction device s resource builds its internal state based single fine grained event stream ensuring consistency integrity When command received Resource Aggregate plgd gateways undergoes validation Upon successful validation event describing action created persisted EventStore Subsequently event published EventBus prevent conflicts during writes EventStore Resource Aggregate utilizes Optimistic concurrency control method Event Store EventStore critical component Resource Aggregate s architecture ensures persistence events operates maintaining append only log guarantees integrity preserves historical changes resource s state enhance performance EventStore creates periodic snapshots resource state based configured N number events It s worth mentioning deduplication mechanism within EventStore may result zero events emitted when command arrives Finally it s important acknowledge single command potential generate multiple events within Resource Aggregate Event Bus EventBus facilitates distribution events various components services within system leveraging EventBus Resource Aggregate seamlessly communicate resource related events system parts promoting decoupling flexibility Resource Aggregate Events pending event valid until time requires confirmation event confirmation event not received valid until time pending event considered invalid discarded Resource Aggregate produces following events Resource Links Events events notify new removal resource links ResourceLinksPublished Indicates resource links published ResourceLinksUnpublished Indicates resource links unpublished ResourceLinksSnapshotTaken Indicates snapshot resource links taken Resource Events events notify resource related events ResourceChanged Indicates resource changed ResourceUpdatePending Indicates resource update pending ResourceUpdated Indicates resource updated ResourceRetrievePending Indicates resource retrieval pending ResourceRetrieved Indicates resource retrieved ResourceDeletePending Indicates resource deletion pending ResourceDeleted Indicates resource deleted ResourceCreatePending Indicates resource creation pending ResourceCreated Indicates resource created ResourceStateSnapshotTaken Indicates snapshot resource state taken Device Metadata Events Device Metadata events provide information device metadata related events including device s online offline status device twin status online status valid time associated needs refreshed gateway gateway fails refresh online status valid time expires device considered offline mechanism ensures online status accurately reflects device s connectivity DeviceMetadataUpdatePending Indicates device metadata update pending used enable disable device twin functionality DeviceMetadataUpdated Indicates device metadata successfully updated DeviceMetadataSnapshotTaken Indicates snapshot device metadata taken", + "objectID": "en/docs/services/resource-aggregate/resource-aggregate", + "description": "What is plgd Resource Aggregate?", + "date": "2023-06-16", + "categories": [ + "storage" + ], + "keywords": [ + "users", + "owners" + ], + "weight": 1, + "isMainSectionPage": true + }, + { + "title": "Tutorials", + "uri": "en/docs/tutorials", + "content": "", + "objectID": "en/docs/tutorials", + "weight": 8 + }, + { + "title": "Device access control list", + "uri": "en/docs/tutorials/acl", + "content": "Defines access device per resource access control list stored device oic sec acl2 resource access control list list access control entries access control entry defines subject set permissions subject subject connection type device role permissions define subject resource permissions defined permission property access control entry permissions defined bit mask following table shows permissions defined permission property Permission Value Notes Create 1 Create resource Read 2 Read resource Write 4 Write resource Delete 8 Delete resource Notify 16 Notify resource IoTivite lite maps permission Create Delete Write permission Notify mapped Read permission When resources subject access use wildcards wildcard property access control resource entry Wildcard Notes Shall match Non Configuration Resources Shall match Discoverable Non Configuration Resources expose least one Secure OCF Endpoint Shall match Non Discoverable Non Configuration Resources expose least one Secure OCF Endpoint device configuration resources need specify href property access control resource entry list device configuration resources Name Type Href Notes Device configuration oic wk con oc con change device name Device maintenance resource oic wk mnt oic mnt factory reset Device cloud resource oic r coapcloudconf CoapCloudConfResURI setup cloud Device firmware update resource oic r softwareupdate oc swu update device firmware Device secure resources oic sec update device secure resources provision state IoTivity href used match ACL When device read ownership transfer method RFOTM state device configuration resources OCF public resources accessible ACL applied normal device state allow access resources RFOTM state need enabled feature IoTivity lite via cmake DOCRESOURCEACCESSINRFOTMENABLED ON when building IoTivity lite mark resource via function ocresourcesetaccessinRFOTM default value OFF update ACL device need provisioning state change device state described here update ACL done via POST method oic sec acl2 resource body aclist2 permission 31 full access resources wc resources if interfaces subject type subject defined body content uuid 00000000 0000 0000 0000 000000000000 device id information ACL found section 12", + "objectID": "en/docs/tutorials/acl", + "description": "How to configure access to the device?", + "date": "2022-12-20", + "categories": [ + "architecture", + "d2c", + "provisioning", + "acl" + ], + "keywords": [ + "architecture", + "d2c", + "provisioning", + "acl" + ], + "weight": 7 + }, + { + "title": "Advanced security", + "uri": "en/docs/tutorials/advanced-security", + "content": "Setup mutual TLS coap gateway set mutual TLS verify signature identity certificate device via configuration api coap tls default clientCertificateRequired true that devices signed identity certificates CA configured coap gateway access hub coap gateway resolves device ID When device makes one calls sign up sign in sign sign off coap gateway needs resolve device ID coap gateway set api coap authorization deviceIDClaim will resolved JWT token JWT token doesn t contain https deviceId returns code Unauthorized closes connection coap gateway set mutual TLS api coap tls clientCertificateRequired will resolved device identity certificate none previous options set device ID will resolved request parameter Don t allow access token doesn t belong device When api coap tls clientCertificateRequired api coap authorization deviceIDClaim set coap gateway matches deviceID certificate JWT token not same coap gateway returns code Unauthorized closes connection push deviceId token auth0 First need create rule Auth pipeline Rules code function user context callback var deviceIdClaim https deviceId var deviceId context context request context request query context request query device_id null deviceId context accessToken deviceIdClaim deviceId return callback null user context that call authorize endpoint obtain authorization code device query parameter device_id device makes sign code returned JWT access token will contain deviceId claim https deviceId validation device ID claim coap gateway api coap authorization deviceIDClaim set https deviceId", + "objectID": "en/docs/tutorials/advanced-security", + "description": "How to secure access devices to coap-gateway", + "docsOthersDisplay": true, + "date": "2021-09-17", + "categories": [ + "tutorials", + "dashboard" + ], + "keywords": [ + "tutorials", + "dashboard" + ], + "weight": 1 + }, + { + "title": "Change the device provisioning status", + "uri": "en/docs/tutorials/change-provision-status", + "content": "update secure device resource credentials ACLs need change device normal state provisioning state current state device use request device provisioning status resource oic sec pstat property dos s state device State name Value Notes Reset 0 Factory reset device will change state RFOTM Ready Device owner transfer method RFOTM 1 Device ready owned Ready Device provisioning RFPRO 2 Update properties secure resources resource owner owner Ready Device normal operation RFNOP 3 Device ready used Device soft reset SRESET 4 Update properties secure resources owner topic find OCF specification section 8 Device Onboarding state definitions change state device use POST request device provisioning status resource need owner device resource owner stored rowneruuid property dos s 2 changing state device update device secure sources credentials ACLs etc updating device secure sources need change state device normal operation dos s 3 startuml Sequence skinparam backgroundColor grey hide footbox box D2D Client participant S Web App n running browser participant C Service n local remote host end box participant D Device n in local network Service S D Update state provisioning state n POST oic sec pstat dos s 2 activate S return Device provisioning state S D Update credentials ACLs etc return Updated S D Update state normal state n POST oic sec pstat dos s 3 return Device normal state deactivate S enduml", + "objectID": "en/docs/tutorials/change-provision-status", + "description": "How to change device provisioning status", + "date": "2021-05-13", + "categories": [ + "tutorials", + "provisioning" + ], + "keywords": [ + "tutorials", + "provisioning" + ], + "weight": 6 + }, + { + "title": "Create & Delete device resources", + "uri": "en/docs/tutorials/create-delete-device-resources", + "content": "Creating resources Device collection resource allows dynamic creation resources created resource defined type see call occollectionsaddrtfactory Guide created resources contained within collection create resource develop own device check example cloud_server Lets examine code identify necessary steps allow device dynamically create resources collection Create collection resource ocresourcet col ocnewcollection NULL switches 1 0 ocresourcebindresourcetype col oic wk col precise description arguments given functions please refer iotivity lite documentation Determine resource types populate collection occollectionaddsupportedrt col oic r switch binary Supported resource types visible oic if baseline interface rts property collection Enable create operation collection resource ocresourcebindresourceinterface col OCIFCREATE Supporting creating resources visible oic if baseline interface property collection support creation resources property contain oic if create interface Define constructor destructor occollectionsaddrtfactory oic r switch binary newswitchinstance freeswitchinstance typedef struct ocswitcht struct ocswitcht next ocresourcet resource bool state ocswitcht OCMEMB switches ocswitcht 1 OC_LIST switches static ocresourcet newswitchinstance const char href ocstringarray_t types ocresourcepropertiest bm ocinterfacemaskt iface_mask size_t device ocswitcht cswitch ocswitcht ocmemballoc switch_s cswitch cswitch resource ocnewresource NULL href ocstringarraygetallocated_size types device cswitch resource size_t i i 0 resource rt ocresourcebindresourceinterface cswitch resource iface_mask cswitch resource properties bm ocresourcesetdefaultinterface cswitch resource OCIFA ocresourcesetrequesthandler cswitch resource OCGET getcswitch cswitch ocresourcesetrequesthandler cswitch resource OCDELETE deletecswitch cswitch ocresourcesetrequesthandler cswitch resource OCPOST postcswitch cswitch ocresourcesetpropertiescbs cswitch resource getswitchproperties cswitch setswitchproperties cswitch ocaddresource cswitch resource ocsetdelayedcallback cswitch resource registerto_cloud 0 oclistinsert switches prev cswitch return cswitch resource ocmembfree switch_s cswitch return NULL static void freeswitchinstance ocresourcet resource ocswitcht cswitch ocswitcht oclisthead switches cswitch cswitch resource resource ocdeleteresource resource oclistremove switches cswitch ocmembfree switch_s cswitch return cswitch oclistitem_next cswitch Compile link enable create operation iotivity lite library compile CREATE 1 option cloud_server CLOUD 1 SECURE 0 CREATE 1 Create resource When hub backend cloud_server binary running use hub client create resource Create go grpc client Go grpc client simple tool supports several useful commands combine create resource Use command identify collection device command retrieves data available devices correctly call create command device id href properties necessary output find item type oic wk col retrieves resources devices grpc get Output content content_type application vnd ocf cbor data n 8 resource_id device_id 2b9ed3ed ddf3 4c9c 4d21 9ec1f6ba6b03 href switches status 1 types oic wk col Create binary switch resource collection grpc create deviceid 2b9ed3ed ddf3 4c9c 4d21 9ec1f6ba6b03 href switches resource static ocresourcet newswitchinstance const char href ocstringarray_t types ocresourcepropertiest bm ocinterfacemaskt iface_mask size_t device ocresourcesetrequesthandler cswitch resource OCGET getcswitch cswitch set delete handler created resource ocresourcesetrequesthandler cswitch resource OCDELETE deletecswitch cswitch ocresourcesetrequesthandler cswitch resource OCPOST postcswitch cswitch Delete go grpc client Delete created binary switch resource collection grpc delete deviceid 2b9ed3ed ddf3 4c9c 4d21 9ec1f6ba6b03 href 4rLN4BlwJmFmbbMJblChB2kyT2zJEP", + "objectID": "en/docs/tutorials/create-delete-device-resources", + "description": "Understand how to create and delete resources hosted by the device dynamically", + "date": "2021-05-13", + "categories": [ + "tutorials", + "device library" + ], + "keywords": [ + "device", + "iotivity", + "create resource", + "delete resource" + ], + "weight": 3 + }, + { + "title": "Branding dashboard", + "uri": "en/docs/tutorials/dashboard-branding", + "content": "plgd hub customization UI company possible includes ability modify logo colors even switch own preferred theme Theme create own theme follow steps Clone repository running following command git clone recursive branch v2 15 0 https github com plgd dev hub git Navigate cloned directory install necessary packages cd hub http gateway web npm install Create own theme within packages shared ui src components Atomic theme mycompany ts directory refer packages shared ui src components Atomic theme plgd ts example cp packages shared ui src components Atomic theme plgd ts packages shared ui src components Atomic theme mycompany ts Build theme executing following command node packages shared ui scripts build theme js themes mycompany generated theme will stored public theme theme json implement changes refresh UI two options First set theme JSON format using Values httpgateway ui theme Helm values file Alternatively directly replace file Docker image path usr local var www theme theme json Favicon favicon png need adjust CSS order Logo rendered correctly size different recommended one modify values left panel scss look classes logo big logo small Adjust height classes fit needs Application name application name appears title bar changed modifying appName field config js Header Status Bar header dedicated component found status bar js modify status bar removing existing components LanguageSwitcher UserWidget adding different content header Footer Footer dedicated component found footer js modify footer tag removing already present links simply adding different content next them Text changes Every text application coming translation file located languages json object contains language block language support application block missing duplicate existing block modify block language code missing messages missing due fact not yet translated add manually use language editor POEditor override strings fit need example Lights name menu call Devices find key menu devices change its value Lights", + "objectID": "en/docs/tutorials/dashboard-branding", + "description": "Change dashboard colors and logo to brand it for your presentation", + "date": "2021-05-13", + "categories": [ + "tutorials", + "dashboard" + ], + "keywords": [ + "dashboard", + "branding", + "logo", + "colors" + ], + "weight": 12 + }, + { + "title": "Dashboard", + "uri": "en/docs/tutorials/developing-dashboard", + "content": "Configuration client found auth_config json domain auth plgd cloud clientID pHdCKhnpgGEtU7KAPcLYCoCAkZ4cYVZg audience https try plgd cloud scope httpGatewayAddress https api try plgd cloud Installation starting development server npm install npm start Application will hosted http localhost 3000 default change default port put PORT xxxx package json script starting development server cross env PORT 3000 craco start set PORT environment variables Building app npm run build Translations order add new language open file config js extend supportedLanguages array additional values Use language code 2 language add supportedLanguages en sk Once added new language open file language switcher i18n js add new entry language added example language code sk entry look this sk id language switcher slovak defaultMessage Slovak Generating language files extracting messages UI components run following script npm run generate pot script will generate template pot file contains strings application ready translated Upload file translation tool translate strings that export po files translations place i18n folder generating language files used application run following script npm run generate language files translations updated ready used Default language default language set en configuration overridden config js changing defaultLanguage field Change language supported application is present supportedLanguages list first visit application browser application will remember current language state order change defaultLanguage field change clear localStorage entry language browser", + "objectID": "en/docs/tutorials/developing-dashboard", + "description": "How to build and configure plgd dashboard", + "date": "2021-05-13", + "categories": [ + "tutorials", + "dashboard" + ], + "keywords": [ + "tutorials", + "dashboard" + ], + "weight": 11 + }, + { + "title": "External OAuth Server with bundle", + "uri": "en/docs/tutorials/external-oauth-server", + "content": "Even though bundle start core plgd services processes single container user possibility configure services parameters testing purposes external OAuth Server e g Auth0 set up skip internal OAuth2 0 Mock Server switch external one configure following environment variables OAUTH_AUDIENCE https api example com OAUTH_ENDPOINT auth example com OAUTHCLIENTID ij12OJj2J23K8KJs OAUTHCLIENTSECRET 654hkja12asd123d OWNER_CLAIM sub configure Auth0 Assuming account Auth0 OAuth service need create 2 Applications one API Follow steps successfully configure bundle run against Auth0 instance Create new API APIs section Use name choice Set unique API identifier e g https api example com saving open details newly created api Enable Offline Access Store internal Auth0 API Id required step 2c Switch Permissions tab add openid scope list Create new Regular Web Application Application section sure Token Endpoint Authentication Method set None Add https FQDN NGINXPORT https FQDN NGINXPORT api authz callback Allowed Callback URLs Add https FQDN NGINX_PORT Allowed Logout URLs Add https FQDN NGINX_PORT Allowed Web Origins Open Advanced Settings switch OAuth tab paste API Id step 1d Switch Grant Types sure Implicit Authorization Code Refresh Token grants enabled Create new Machine Machine Application Application section Set Token Endpoint Authentication Method Post Add https FQDN NGINX_PORT Allowed Callback URLs Add https FQDN NGINX_PORT Allowed Web Origins Open Advanced Settings switch OAuth tab paste API Id step 1d Switch Grant Types sure Client Credentials grant enabled", + "objectID": "en/docs/tutorials/external-oauth-server", + "description": "Use your custom external OAuth Server with plgd bundle", + "date": "2021-05-13", + "categories": [ + "tutorials", + "authorization" + ], + "keywords": [ + "bundle", + "oauth", + "auth0" + ], + "weight": 4 + }, + { + "title": "Onboarding to plgd hub", + "uri": "en/docs/tutorials/how-to-onboard-device-to-hub", + "content": "Device remotely accessed when it s onboarded connected plgd hub connection device hub secure CoAP TCP UDP connection Combination JWT token Identity certificate guarantees zero trust security end to end integration onboard device plgd hub following configuration data needed coapGatewayAddress address plgd hub format authorizationCode OAuth2 0 authorization code used device JWT token authorizationProviderName authorization provider used authorize device plgd hub hubID id plgd hub certificateAuthorities trusted certificates used verify authenticity plgd hub device owner Zero touch Provisioning service authorized client allowed provision device configuration data required device cloud connectivity device onboarding process starts right successful provisioning onboard enable device cloud connectivity following tasks need successfully completed Certificate Authority configured so device successfully verify authenticity plgd hub ACLs configured so device authorizes incoming requests plgd hub hub onboarding configuration set so device knows connect authorize connection steps reduced one click when using Device Device Client fully automated when using Zero Touch Provisioning Certificate Authority configuration Certificates configured provisioning state information process found here When device provisioning state add certificate authority device credentials resource body creds subjectuuid plgd hub ID credtype 8 credusage oic sec cred trustca publicdata data BEGIN CERTIFICATE n n END CERTIFICATE n encoding oic sec encoding pem information credentials resource found section 9 update device credentials done via POST method oic sec cred resource startuml Sequence skinparam backgroundColor grey hide footbox box D2D Client participant S Web App n running browser participant C Service n local remote host end box participant D Device n in local network Service S D Update credentials n POST oic sec cred creds activate S return Credentials updated deactivate S enduml Device ACLs device acts server uses concepts ACLs client authorization information ACLs configure found here Hub device communication device needs following ACLs configured aclist2 permission 31 full access resources wc update get resources if interfaces href oc con update get device name if interfaces href oc swu update get device firmware if interfaces subject type subject defined body content uuid hub id Hub id update device ACL done via POST method oic sec acl2 resource startuml Sequence skinparam backgroundColor grey hide footbox box D2D Client participant S Web App n running browser participant C Service n local remote host end box participant D Device n in local network Service S D Update ACL n POST oic sec acl2 aclist2 activate S return ACL updated deactivate S enduml Hub Onboarding Configuration device hosts coapcloudconfresource hub onboarding configuration set Resource definition found here Setting resource required values will trigger onboarding process detail described here Connection authentication encryption Connection plgd hub secured using X 509 certificate device mutually authenticates cloud certificate used depends credentials available device Following table gives information mTLS enabled certificate used connection Manufacturer Certificate Identity Certificate mTLS plgd hub possible Device authenticates using no no no mTLS not possible yes no yes manufacturer certificate yes no yes yes identity certificate Manufacturer certificate flashed or contained within TPM device during production Identity Certificate one option device credentials set during device ownership transfer PSK that s why Identity Certificate doesn t present connect plgd hub plgd hub requires mTLS authentication device needs identity manufacturer certificate signed certificate authority known plgd hub onboard device plgd hub device provisioned authorization code acquired device need owned authorization code used authorize device plgd hub startuml Sequence skinparam backgroundColor grey hide footbox box D2D Client participant S Web App n running browser participant C Service n local remote host end box participant D Device n in local network Service box plgd hub participant OA OAuth 2 0 Server end box S OA authorization code n deviceID clientID scopes audience activate S return Authorization code S D Onboard plgd hub n coapGatewayAddress authorizationCode authorizationProviderName hubID certificateAuthorities return Device starts connect plgd hub loop until device not registered fail state S D cloud provision status end", + "objectID": "en/docs/tutorials/how-to-onboard-device-to-hub", + "description": "How to onboard the device to the plgd hub?", + "date": "2022-12-13", + "categories": [ + "architecture", + "d2c", + "provisioning", + "onboarding" + ], + "keywords": [ + "architecture", + "d2c", + "provisioning", + "onboarding", + "oauth" + ], + "weight": 20 + }, + { + "title": "Setting Up Plgd Hub and Plgd DPS in a Dynamic IP Environment (DHCP)", + "uri": "en/docs/tutorials/laptop-deployment", + "content": "scenarios IP addresses change DHCP you ll need configure plgd hub plgd dps Device Provisioning Service using dynamic static IP address Configuring System accommodate dynamic static IP addresses follow steps Add Additional IP Secondary IP Ubuntu System achieved referring guides as Add Additional IP Secondary IP Ubuntu System Ask Ubuntu Does netplan support DHCP static addresses one interface Assign static IP address example 10 254 254 1 32 Update etc hosts file domains pointing static IP address 10 254 254 1 demo mycompany com auth demo mycompany com api demo mycompany com Installing Configuring DNS Server Install DNS server dnsmasq serve domains MicroK8s configuration permanent reboots Allow server listen 10 254 254 1 Configuring MicroK8s Use Custom DNS Configure MicroK8s utilize custom DNS server IP 10 254 254 1 following MicroK8s documentation adding custom DNS add on Updating Helm Values PLGD Services Adjust Helm values YAML PLGD services utilize domain DHCP assigned IP address Modify values yaml following settings global domain demo mycompany com coapgateway apis coap externalAddress resourcedirectory publicConfiguration coapGateway coaps tcp deviceProvisioningService enrollmentGroups id hub coapGateway Replace actual DHCP assigned IP address port Sustaining IP Address Changes changing IP address need update values yaml Helm changes effect coap gateway resource directory device provisioning service pods will restarted load configuration Accessing Services Ensure laptop attempting access https demo mycompany com updated etc hosts file pointing new DHCP assigned IP address", + "objectID": "en/docs/tutorials/laptop-deployment", + "description": "How to setting up Plgd Hub and Plgd DPS in a Dynamic IP Environment (DHCP)", + "docsOthersDisplay": true, + "date": "2023-08-09", + "categories": [ + "tutorials", + "deployment", + "advanced" + ], + "keywords": [ + "tutorials", + "dhcp", + "laptop" + ], + "weight": 1 + }, + { + "title": "OCF Conformance Testing", + "uri": "en/docs/tutorials/ocf-conformance-testing", + "content": "Open Connectivity Foundation OCF global member driven technical standard development organization Its 500 members working enable trust interoperability secure communication IP connected IoT devices services does fostering collaboration stakeholders across IoT ecosystem deliver freely available ISO IEC specifications including Secure IP Device Framework its open source reference implementation industry recognized certification program OCF Certification Program includes conformance testing ensure robust secure connectivity help manufacturers create products just work OCF Certified IoT devices regardless form factors operating systems service providers transports plgd hub reference implementation OCF Device Cloud Services OCF Cloud API Cloud Services specifications automatically tested OCF Conformance Test Tool CTT guarantees interoperability OCF Certified IoT devices Clouds user plgd hub interested OCF Certification tutorial will guide execute required OCF test cases validate conformance OCF uses Windows based application called Conformance Test Tool CTT succeed validation correctly set environment configuration file CTT following sections will explain necessary steps Environment environment used tutorial consists following parts Windows 10 host machine Ethernet connection Ubuntu 20 04 3 LTS running Oracle VM VirtualBox 6 1 Set Windows host machine Download CTT tool only available registered users Install CTT host machine default installation located C Program Files x86 OCF Conformance Test Tool Install ngrok set described CTT User Guide located C Program Files x86 OCF Conformance Test Tool Docs Users Guide mhtml Follow section named C2C Accessibility Examine Ubuntu machine VirtualBox go Settings Network pane sure least one adapter enabled Attached to setting set Bridged Adapter value Run plgd hub bundle Ubuntu machine services implementing Origin Cloud Target Cloud API available Windows host machine therefore several environmental variables defined Run following commands HOME folder terminal docker run it rm e FQDN 192 168 1 44 network host ghcr io plgd dev hub bundle latest Value FQDN machine dependent followed previous steps changed network settings guest machine Bridged Adapter obtain address running ifconfig terminal taking ipv4 address active network interface correctly setting FQDN variable docker command start services guest machine GUI provided plgd hub bundle available address set FQDN environmental variable example https 192 168 1 44 Please verify opening address browser Windows host machine Validating C2C Target Cloud Conformance Target Cloud API implemented cloud2cloud gateway service part plgd hub bundle Create CTT Target Cloud configuration file run CTT test cases PICS configuration file required Several files provided CTT installation among example configuration file named PICSC2CTargetCloudexample json example file fields modified based environment fields explained CTT User Guide supportedDeviceTypes oic d switch authorizationEndpointUrl https FQDN authorize audience https FQDN tokenEndpointUrl https FQDN oauth token c2cApiUrl https FQDN c2c gw retrievalScope r offline_access updateScope r w offline_access cloudServerTrustAnchorCertificate validClientId testC2C validClientSecret testC2CSecret supportsResourcesPublishedUnpublishedEvents true localEventListenerUri https localhost 55551 events_123 proxyEventListenerUri https 4561 95 102 120 86 ngrok io events_123 Properties authorizationEndpointUrl tokenEndpointUrl c2cApiUrl contain address plgd hub bundle against CTT executes tests Please update match FQDN value plgd hub bundle contains mock OAuth2 0 Server simplifies development conformance testing values localEventListenerUri proxyEventListenerUri provided ngrok application guide obtain described User Guide section Setup Target Cloud test cases Events API CT5 3 X cloudServerTrustAnchorCertificate value contain correctly formatted certificate formatted one liner Windows line endings as cloudServerTrustAnchorCertificate BEGIN CERTIFICATE r n r n END CERTIFICATE certificate retrieved plgd hub bundle opening https FQDN well known configuration Copy value certificateAuthorities property cloudServerTrustAnchorCertificate value proper formatting certificate regenerated whenever plgd hub bundle started So restart bundle instance update PICS configuration well Start Conformance Test Tool following previous steps running plgd hub bundle Ubuntu machine running ngrok application prepared PICS configuration file Windows machine start CTT application Go File Select IUT select Target Cloud click Next next pane IUT Selection click Browse navigate created PICS configuration select click Next twice Cloud tests list loaded 6 CT5 x x C2C test cases available Using Iotivity lite devices Several CTT test cases require 1 devices running Moreov", + "objectID": "en/docs/tutorials/ocf-conformance-testing", + "description": "How to validate conformance to OCF C2C and D2C API?", + "date": "2021-12-11", + "categories": [ + "tutorials", + "ctt" + ], + "keywords": [ + "OCF conformance", + "tutorial", + "CTT tool" + ], + "weight": 10 + }, + { + "title": "Share devices within user groups", + "uri": "en/docs/tutorials/shared-ownership", + "content": "Devices organized Identity Store service owner ID retrieved JWT token plgd API will based value identify user grant permissions devices owns default JWT claim sub used owner ID case connect plgd authorization service Auth0 logged in user access devices behaviour changed changing OWNER_CLAIM configuration property adding custom claim Auth0 users use custom claim Auth0 Assign claim user Go Users Roles Find user edit details Extend user_metadata custom claim e g tenant e3e0102d a45b 5cb2 a22e 3a0410deb8d6 Assign wildcard permission service client Go Applications Edit Machine Machine application Open Advanced Settings switch Application Metadata add entry Key tenant Value Include custom claim access token Go Rules create new one Copy paste function below uses custom claim https plgd dev tenant function addTenantToAccessToken user context callback var tenantClaim https plgd dev tenant var tenant user user usermetadata user usermetadata tenant context context clientMetadata context clientMetadata tenant null tenant context accessToken tenantClaim tenant context idToken tenantClaim tenant return callback null user context rule created Auth0 include every access tokens custom claim https plgd dev tenant used group users their devices case custom OWNER_CLAIM configured devices no owned single user case tenant user member tenant will able access devices tenant configuration property OWNER_CLAIM changed user required claim present", + "objectID": "en/docs/tutorials/shared-ownership", + "description": "Share devices with more than one person identified as owner", + "date": "2021-05-13", + "categories": [ + "tutorials", + "authorization" + ], + "keywords": [ + "bundle", + "ownership", + "device group", + "oauth", + "auth0" + ], + "weight": 8 + }, + { + "title": "Testing", + "uri": "en/docs/tutorials/testing", + "content": "Testing plgd hub pull requests When developer creates pull request plgd hub automatically triggers tests tests pulls latest IoTivity lite release represented docker image ghcr io iotivity iotivity lite cloud server debug latest contains functionality run hub updated when new IoTivity lite release published startuml skinparam backgroundColor grey hide footbox participant D Developer participant CI plgd hub continuous integration participant IL IoTivite Lite D CI Create Update pull request group Continuous integration CI IL Pull latest cloud server image IoTivity Lite return latest cloud server image CI CI Setup environment CI CI Run hub tests pull request end CI D Inform developer when error occurs email enduml Testing IoTivity lite pull requests When developer creates pull request iotivity lite automatically triggers tests tests pulls latest plgd hub release represented docker image ghcr io plgd dev hub test cloud server latest contains functionality used plgd hub updated when new plgd hub release published startuml skinparam backgroundColor grey hide footbox participant D Developer participant CI IoTivity Lite continuous integration participant PH plgd hub D CI Create Update pull request group Continuous integration CI PH Pull latest test cloud server image plgd hub return latest test cloud server image CI CI Setup environment CI CI Run test cloud server againt current iotivity lite cloud server end CI D Inform developer when error occurs email enduml", + "objectID": "en/docs/tutorials/testing", + "description": "How plgd hub tests iotivity-lite and vice versa", + "date": "2021-10-14", + "categories": [ + "tutorials", + "testing" + ], + "keywords": [ + "tutorials", + "testing" + ], + "weight": 9 + }, + { + "title": "Working with gRPC Client", + "uri": "en/docs/tutorials/working-with-grpc-client", + "content": "creating grpc client need generate code language proto files stored plgd hub plgd gRPC Gateway uses TLS client needs therefore properly configured TLS simple example create secured gRPC client communicating plgd gRPC Gateway import google golang org grpc google golang org grpc credentials github com plgd dev hub v2 grpc gateway pb github com plgd dev hub v2 grpc gateway client Create TLS connection grpc gateway gwConn err grpc Dial address grpc WithTransportCredentials credentials NewTLS tlsConfig err nil panic cannot connect grpc gateway err Error Create basic client generated proto files basicClient pb NewGrpcGatewayClient gwConn Create Extended client provide us friendly functions extendedClient client NewClient basicClient Using extended gRPC Client info doc API requests service contain valid access token grpc metadata request gRPC Gateway shall contain valid access token part grpc metadata Devices GetDevices command supports various filter options unset devices user identified access token returned Example usages filter options retrieve certain devices use GetDevicesRequest deviceidfilter ids devices need set retrieve offline devices set GetDevicesRequest status_filter OFFLINE retrieve devices certain types use GetDevicesRequest type_filter e g x com plgd light return ONLINE devices ids deviceID1 deviceID2 following options shall set GetDevicesRequest deviceidfilter deviceID1 deviceID2 GetDevicesRequest status_filter ONLINE Resource Links GetResourceLinks command supports various filter options unset links devices user authorized use returned Example usages filter options retrieve links certain devices use GetResourceLinksRequest deviceidfilter ids devices needs set retrieve links certain types use GetResourceLinksRequest type_filter e g oic r switch binary return binary switches resources hosted devices ids deviceID1 deviceID2 following options shall set GetResourceLinksRequest deviceidfilter deviceID1 deviceID2 GetResourceLinksRequest type_filter oic r switch binary Resource Content GetResources command supports various filter options unset resource contents device twin devices user authorized use returned Example usages filter options retrieve resources identified hrefs use GetResourcesRequest resourceidfilter combinations deviceID href required format deviceID href retrieve resource values certain devices use GetResourcesRequest deviceidfilter ids devices need set retrieve values resources specific type use GetResourcesRequest type_filter return values binary switch resources hosted devices ids deviceID1 deviceID2 following options shall set GetResources deviceidfilter deviceID1 deviceID2 GetResources type_filter oic r switch binary Subscribe Events SubscribeToEvents command opens stream content driven control message control content stream send SubscribeToEvents message following options example Set action createsubscription eventfilter DEVICEMETADATAUPDATED receive events devices changed status e g ONLINE OFFLINE among selected devices deviceidfilter Set action createsubscription deviceidfilter eventfilter set eventfilter RESOURCEPUBLISHED RESOURCEUNPUBLISHED receive device events selected devices deviceid_filter Use action createsubscription hreffilter receive resource events devices selected resources specified href_filter Set action createsubscription deviceidfilter hreffilter eventfilter set eventfilter CONTENTCHANGED receive resource events filtered resources specified hreffilter among selected devices deviceidfilter Use action createsubscription resourceidfilter receive resource events selected device resources specified resourceid_filter no filters set using action create_subscription alone will receive device events hub first event returned successful subscription type OperationProcessed Property OperationProcessed error_status code contains information subscription successful successful property subscriptionId set events belonging single SubscribeToEvents request identified subscriptionId user loses device unregistered no shared user client receives event SubscriptionCanceled corresponding subscription_id Resource Device GetResourceFromDevice retrieves resource content directly device device twin resource value not returned define expiration command set GetResourceFromDeviceRequest timetolive nanoseconds minimal 100ms pending event expired GetResourceFromDevice valid_until Unix timestamp nanoseconds 0 means forever hub skips will removed creating new snapshot event command execution expensive reach real device client synchronously waits response Update Resource Content UpdateResource command requests resource updates device define expiration command set UpdateResourceRequest timetolive nanoseconds minimal 100ms pending event expired ResourceUpdatePending valid_until Unix timestamp nanoseconds 0 means forever hub skips will removed creating new snapshot event Create Resource Create Resource comman", + "objectID": "en/docs/tutorials/working-with-grpc-client", + "description": "Understading API of gRPC Gateway and how to use it in your application", + "date": "2021-05-13", + "categories": [ + "tutorials", + "grpc gateway" + ], + "keywords": [ + "grpc", + "gateway", + "client" + ], + "baseURL": "https://url.test.com", + "output": [ + "JSON" + ], + "weight": 5, + "algolia": { + "indexName": "doc", + "apiKey": "31dbe24685b8a1a7025c12098b32df37", + "appId": "42D6VHXINQ" + } + } +] \ No newline at end of file diff --git a/tools/adjust-algolia-output/go.mod b/tools/adjust-algolia-output/go.mod new file mode 100644 index 00000000..cf44cf7b --- /dev/null +++ b/tools/adjust-algolia-output/go.mod @@ -0,0 +1,5 @@ +module github.com/plgd-dev/doc/tools/adjust-algolia-output + +go 1.22.0 + +require github.com/ugorji/go/codec v1.2.12 diff --git a/tools/adjust-algolia-output/go.sum b/tools/adjust-algolia-output/go.sum new file mode 100644 index 00000000..46a9a427 --- /dev/null +++ b/tools/adjust-algolia-output/go.sum @@ -0,0 +1,2 @@ +github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE= +github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg= diff --git a/tools/adjust-algolia-output/main.go b/tools/adjust-algolia-output/main.go new file mode 100644 index 00000000..4565030e --- /dev/null +++ b/tools/adjust-algolia-output/main.go @@ -0,0 +1,99 @@ +package main + +import ( + "flag" + "fmt" + "io" + "os" + "path/filepath" + "regexp" + "strings" + + "github.com/ugorji/go/codec" +) + +type arrayFlags []string + +func (i *arrayFlags) String() string { + return "my string representation" +} + +func (i *arrayFlags) Set(value string) error { + *i = append(*i, value) + return nil +} + +// WriteTo writes v to writer. +func WriteTo(w io.Writer, v interface{}) error { + var h codec.JsonHandle + h.BasicHandle.Canonical = true + err := codec.NewEncoder(w, &h).Encode(v) + if err != nil { + return fmt.Errorf("JSON encoder failed: %w", err) + } + return nil +} + +// ReadFrom reads and stores the result in v. +func ReadFrom(w io.Reader, v interface{}) error { + var h codec.JsonHandle + err := codec.NewDecoder(w, &h).Decode(v) + if err != nil { + return fmt.Errorf("JSON decoder failed: %w", err) + } + return nil +} + +func getParentID(objectID string) string { + return filepath.Dir(objectID) +} + +func main() { + rootObjectIDRegex := flag.String("root-object-id", "[a-z0-9A-Z]+/docs$", "Root object ID for the adjust title - if empty, no adjustment is made, if set the string will be used as separator") + adjustTitle := flag.String("adjust-title", " / ", "Adjust title - if empty, no adjustment is made, if set the string will be used as separator") + trimPrefixesInURI := arrayFlags{"en/"} + flag.Var(&trimPrefixesInURI, "trim-prefixes-in-uri", "Remove the given prefixes in the URI") + flag.Parse() + + var data []map[string]interface{} + err := ReadFrom(os.Stdin, &data) + if err != nil { + fmt.Fprintf(os.Stderr, "Error: %v\n", err) + os.Exit(1) + } + var regexpRootObjectID *regexp.Regexp + if *rootObjectIDRegex != "" && *adjustTitle != "" { + regexpRootObjectID = regexp.MustCompile(*rootObjectIDRegex) + } + mapping := make(map[string]map[string]interface{}) + for _, item := range data { + objectID := item["objectID"].(string) + mapping[objectID] = item + } + for idx, item := range data { + for _, prefix := range trimPrefixesInURI { + item["uri"] = strings.TrimPrefix(item["uri"].(string), prefix) + } + if regexpRootObjectID != nil { + parentID := getParentID(item["objectID"].(string)) + for { + if regexpRootObjectID.Match([]byte(parentID)) { + break + } + parent, ok := mapping[parentID] + if !ok { + break + } + item["title"] = fmt.Sprintf("%v%s%v", parent["title"], *adjustTitle, item["title"]) + parentID = getParentID(parentID) + } + } + data[idx] = item + } + err = WriteTo(os.Stdout, data) + if err != nil { + fmt.Fprintf(os.Stderr, "Error: %v\n", err) + os.Exit(1) + } + +}