Add bascloud to latest

[bascloud]

Please add my adapter ioBroker.bascloud to latest.

This pull request was created by https://www.iobroker.dev c0726ff.

[mcm1957]

@bascloud

Thanks for spending your time and providing a new adapter for ioBroker.

Your adapter will get a manual review as soon as possible. Please stand by - this might last one or two weeks. Feel free to continue your work and create new releases. You do NOT need to close or update this PR in case of new releases.

In the meantime please check any feedback issues logged by automatic adapter checker and try to fix them.

You will find the results of the review and eventually issues / suggestings as a comment to this PR. So please keep this PR watched.

If you have any urgent questions feel free to ask.

reminder 11.6.2024

[mcm1957]

@bascloud
Sorry for the delay. I'm on holiday until 20.6. So the review might still last a little bit.

[mcm1957]

First of all - THANK YOU for the time and effort you spend to maintain this adapter.
And thnaks for your patience. Was on holidays a second time until yesterday.

I would like to give some feedback based on my personal oppinion. @Apollon77 might have additional suggestions or even a different oppinion to one or the other statement. Please feel free to contact him if you cannot follow my suggestions or want to discuss some special aspects.

• Readme.md contains developer information

  Please remove all developer related information from README. README should contain a short information for users hwo to use the adapter (or a link to a documentation describing the usage of the adapter - typically locaed at directry /doc).

• Readme.md should contain a link to the manufacturer and/or device

  The README.md of any adapter related to device or m ultiple devices of a manufacturer should contain a link the manufacturers website and/or to a description of the device. This is to anable new users to easily check wether they associate the adapter with the correct device(s). (See https://github.com/ioBroker/ioBroker.repositories#requirements-for-adapter-to-get-added-to-the-latest-repository paragraph 4.)

• package.json should require up to date js-controller and admin version

  New adapters should request js-controller 5 and admin 6 as minimum if there are no strong reason to support (and test) older releases. So please add / adapt at io-package.json:

        "dependencies": [
            {
                "js-controller": ">=5.0.19"
            }
        ],
        "globalDependencies": [
            {
                "admin": ">=6.13.16"
            }
        ]
  

• invalid characters must be filtered from object ids

  Some characters are not allowed to be used as part of an object id. If an object id is not hardcoded or even depending on user input you should ensure that such an object id does not contain an invalid character. Iobroker provides the constant adapter.FORBIDDEN_CHARS, i.e. by using the following snippet:

  function name2id(pName) {
      return (pName || '').replace(adapter.FORBIDDEN_CHARS, '_');
  }
  

  Looks like ids are configured by user. So this data MUST be filtered. Minimum filtering is to use FORBIDDEN_CHARS. The optimal strategy for new adapters is to allow ONLY 0-9,1-zA-z_-. Note that blanks should be removed / replaced as some vis adapters cannot process them. And please note that the dot has ha special meaning as folder seperator. So either dots must be removed/replaces or code maust take care to create potential folders defined this way.

• onStateChange must check id

  If someone writes to a state which is not listed at your readingsWrite adapter will crash. This must be checked
  https://github.com/bascloud/ioBroker.bascloud/blob/1c716a5c89f00f702d19e5d934669f4b7694cc69/src/main.ts#L169

• write:true set for read states

  Why do you set write:true at reading.localId states? It looks like that twriting to those states is not processed at onStateChange anyway. See https://github.com/bascloud/ioBroker.bascloud/blob/1c716a5c89f00f702d19e5d934669f4b7694cc69/src/main.ts#L96

• reevaluate state roles

  Only the values specified here (https://github.com/ioBroker/ioBroker.docs/blob/master/docs/en/dev/stateroles.md) may be used as state roles. Do not invent new names as this might disturb the functionalyity of other adapters or vis.

  In addition the roles MUST match the read/write functionality. As an example a role value.* requires that the state is a readable state. Input states (write only) should have roles like level.*. Please read the description carefully. States with role 'button' should (must) have attribute 'common.read=false' set. A button ( "Taster" in german only triggers when you press but else has no state), so it should also be not readable. This is also like HomeMatic does it. A switch has clear states true or false and so can be read.

  Please avoid using general roles (state, value) whnever a dedicated role exists.

  role:indicator required type boolean and ReadOnly. So 'value' would match best if write:false, otherwise evaluate 'level'

• some labels seem to have no translation into all languages

  It seems that some labels are not translated into all supported languages. You must enter the keys into english translations.json (i18n/en/translations.json() and run 'npm run translate' to generate the translation for other languages.

• consider using adapter.setTimeout / this.setTimeout instead of (standard) setTimeout

  The adapter package provides wrapper routines for native setTimeout, setInterval, clearTimeout and clearInterval. Using those routines ensures that timers are cancelled on on load. Additional checks on thomse limits might be performed, too. So consider replacing native setTimeout/clearTimeout by adapter.setTimeout/adapter.clearTimeout or this.setTimeout/this.clearTimeout. The same refers to setInterval/clearInterval.

• check and limit configurable timeouts / intervals

  Node setTimeout/setInterval routines have a maximum allowed value of 2,147,483,647 ms. Using delays larger than 2,147,483,647 ms (about 24.8 days) result in the timeout being executed immediately. So all (user configurable) values passed to setTimeout / setInterval should be checked in code and limited. Checking/limiting in code is required as config data could be changed directly or by some other adapter too, so limiting at ui level might not be sufficient.

• check and limit intervals used to access cloud services

  Limit all intervals used to access cloud services to a reasonable value. If users configure an inapprobiate access rate this could lead to suspending the service by the provider for all ioBroker users.

• ensure correct type

  own states are always created with type number. So you must ensure that the data read from bascloud is really a number. See https://github.com/bascloud/ioBroker.bascloud/blob/1c716a5c89f00f702d19e5d934669f4b7694cc69/src/main.ts#L213. Currently users will get logs if data received is not a number. The type of the val paramater passed to setState must match the type specified at state creation.

• adapt testing to supported node releases

  Tests for node 18 and 20 are mandatory as these are the officially supported node versions.
  Tests for node 22 are suggested and should be added for new adapters.

  So the recommended testmatrix is [18.x, 20.x, 22.x] depending on engines requirments setting at package.json

  Tests must be performed at all supported platforms (linux, windows, mac) unless special hardware or software restrictions prohibit this.

Thanks for reading and evaluating this suggestions.
McM1957

Please add a comment when you have reviewed and fixed the suggestionsor at least commented the suggestions and you think the adapter is ready for a re-review!

reminder 27.07.2024

[bascloud]

So I just did a massive update with all the said changes you proposed:

• README no longer contains development information
• README contains a link to our website
• io-package.json requires up-to-date js-controller and admin
• object ids are now validated
• onStateChange now checks for undefined
• set write to false for read-only states
• set state role to state
• all labels have translations now
• using this.setInterval instead of setInterval
• limiting the interval to the maximum and logging it as error
• added macos and windows testing as well as nodejs 22.x

The points about limiting access to the cloud services and ensuring the correct type are irrelevant. But we will continue to monitor from our side and adjust when needed!

Thank you for your time reviewing our adapter. If there is any other feedback or if you need us to make other changes to fully comply, just let me know!

Hope you had wonderful holidays! :D

~ Yanick

[github-actions]

Automated adapter checker

ioBroker.bascloud

-

👍 No errors found

• 👀 [W034] @iobroker/adapter-core 3.1.5 specified. 3.1.6 is recommended. Please consider updating dependencies at package.json
• 👀 [W400] Cannot find "bascloud" in latest repository

Add comment "RE-CHECK!" to start check anew

[mcm1957]

RECHECK

• Readme.md contains developer information

  Please remove all developer related information from README. README should contain a short information for users hwo to use the adapter (or a link to a documentation describing the usage of the adapter - typically locaed at directry /doc).

• Readme.md should contain a link to the manufacturer and/or device

  The README.md of any adapter related to device or m ultiple devices of a manufacturer should contain a link the manufacturers website and/or to a description of the device. This is to anable new users to easily check wether they associate the adapter with the correct device(s). (See https://github.com/ioBroker/ioBroker.repositories#requirements-for-adapter-to-get-added-to-the-latest-repository paragraph 4.)

• package.json should require up to date js-controller and admin version

  New adapters should request js-controller 5 and admin 6 as minimum if there are no strong reason to support (and test) older releases. So please add / adapt at io-package.json:

        "dependencies": [
            {
                "js-controller": ">=5.0.19"
            }
        ],
        "globalDependencies": [
            {
                "admin": ">=6.13.16"
            }
        ]
  

• invalid characters must be filtered from object ids

  Some characters are not allowed to be used as part of an object id. If an object id is not hardcoded or even depending on user input you should ensure that such an object id does not contain an invalid character. Iobroker provides the constant adapter.FORBIDDEN_CHARS, i.e. by using the following snippet:

  function name2id(pName) {
      return (pName || '').replace(adapter.FORBIDDEN_CHARS, '_');
  }
  

  Looks like ids are configured by user. So this data MUST be filtered. Minimum filtering is to use FORBIDDEN_CHARS. The optimal strategy for new adapters is to allow ONLY 0-9,1-zA-z_-. Note that blanks should be removed / replaced as some vis adapters cannot process them. And please note that the dot has ha special meaning as folder seperator. So either dots must be removed/replaces or code maust take care to create potential folders defined this way.

• onStateChange must check id

  If someone writes to a state which is not listed at your readingsWrite adapter will crash. This must be checked
  https://github.com/bascloud/ioBroker.bascloud/blob/1c716a5c89f00f702d19e5d934669f4b7694cc69/src/main.ts#L169

• write:true set for read states

  Why do you set write:true at reading.localId states? It looks like that twriting to those states is not processed at onStateChange anyway. See https://github.com/bascloud/ioBroker.bascloud/blob/1c716a5c89f00f702d19e5d934669f4b7694cc69/src/main.ts#L96

• reevaluate state roles

  Only the values specified here (https://github.com/ioBroker/ioBroker.docs/blob/master/docs/en/dev/stateroles.md) may be used as state roles. Do not invent new names as this might disturb the functionalyity of other adapters or vis.

  In addition the roles MUST match the read/write functionality. As an example a role value.* requires that the state is a readable state. Input states (write only) should have roles like level.*. Please read the description carefully. States with role 'button' should (must) have attribute 'common.read=false' set. A button ( "Taster" in german only triggers when you press but else has no state), so it should also be not readable. This is also like HomeMatic does it. A switch has clear states true or false and so can be read.

  Please avoid using general roles (state, value) whnever a dedicated role exists.

  role:indicator required type boolean and ReadOnly. So 'value' would match best if write:false, otherwise evaluate 'level'

• some labels seem to have no translation into all languages

  It seems that some labels are not translated into all supported languages. You must enter the keys into english translations.json (i18n/en/translations.json() and run 'npm run translate' to generate the translation for other languages.

• consider using adapter.setTimeout / this.setTimeout instead of (standard) setTimeout

  The adapter package provides wrapper routines for native setTimeout, setInterval, clearTimeout and clearInterval. Using those routines ensures that timers are cancelled on on load. Additional checks on thomse limits might be performed, too. So consider replacing native setTimeout/clearTimeout by adapter.setTimeout/adapter.clearTimeout or this.setTimeout/this.clearTimeout. The same refers to setInterval/clearInterval.

• check and limit configurable timeouts / intervals

  Node setTimeout/setInterval routines have a maximum allowed value of 2,147,483,647 ms. Using delays larger than 2,147,483,647 ms (about 24.8 days) result in the timeout being executed immediately. So all (user configurable) values passed to setTimeout / setInterval should be checked in code and limited. Checking/limiting in code is required as config data could be changed directly or by some other adapter too, so limiting at ui level might not be sufficient.

• check and limit intervals used to access cloud services

  Limit all intervals used to access cloud services to a reasonable value. If users configure an inapprobiate access rate this could lead to suspending the service by the provider for all ioBroker users.

• ensure correct type

  own states are always created with type number. So you must ensure that the data read from bascloud is really a number. See https://github.com/bascloud/ioBroker.bascloud/blob/1c716a5c89f00f702d19e5d934669f4b7694cc69/src/main.ts#L213. Currently users will get logs if data received is not a number. The type of the val paramater passed to setState must match the type specified at state creation.

• adapt testing to supported node releases

  Tests for node 18 and 20 are mandatory as these are the officially supported node versions.
  Tests for node 22 are suggested and should be added for new adapters.

  So the recommended testmatrix is [18.x, 20.x, 22.x] depending on engines requirments setting at package.json

  Tests must be performed at all supported platforms (linux, windows, mac) unless special hardware or software restrictions prohibit this.

[mcm1957]

Looks good now. The following remark is still open:

• [ } invalid characters must be filtered from object ids

  Some characters are not allowed to be used as part of an object id. If an object id is not hardcoded or even depending on user input you should ensure that such an object id does not contain an invalid character. Iobroker provides the constant adapter.FORBIDDEN_CHARS, i.e. by using the following snippet:

  function name2id(pName) {
      return (pName || '').replace(adapter.FORBIDDEN_CHARS, '_');
  }
  

  Looks like ids are configured by user. So this data MUST be filtered. Minimum filtering is to use FORBIDDEN_CHARS. The optimal strategy for new adapters is to allow ONLY 0-9,1-zA-z_-. Note that blanks should be removed / replaced as some vis adapters cannot process them. And please note that the dot has ha special meaning as folder seperator. So either dots must be removed/replaces or code maust take care to create potential folders defined this way.

  You have added checks at jsonConfig. This is OK and helps users to avoid incorret entried.

  I stringly recommend to add checks at code too as sers can (and some will) change the confivuration by direct access to the insatance object.

I do not consider this as blocking - so I will release the adapter. But as written above I suggest to add such a check to your code with next release.

[mcm1957]

This adapter has been released to latest repository and should be visible within 24h maximum.

Please create a thread at https://forum.iobroker.net/category/91/tester titled like "Test Adapter " to collect some user feedback and provide a link to this topic when requesting addition to stable repository later.

Note: If an other testing topic already exists, it' OK to continue using this topic too.