Generic tutorials

1

Hi,
I miss some more generic documentation related to BC ecosystem.

I realised that when I tried (and failed) rewrite VOC demo project to my needs (no LCD, no chart functionality, just read the value and send it through MQTT). I found, that you are not consistent with scheduler usage across projects. In VOC you are using bc_scheduler_plan_now(APPLICATION_TASK_ID) while on others (like climate module project) you just setup scheduler and check tick inside handler.

I will be really happy to have access to docs about generic usage of scheduler and various ways how to use it. It will be very helpful for me as C language and firmware level programming is not part of my daily job.

Thanks
Michal

2

Hi,

some doc is here https://www.bigclown.com/doc/firmware/timing-and-scheduler/
and here http://sdk.bigclown.com/group__bc__scheduler.html

we have two possibility planning task:

  1. Inside task bc_scheduler_plan_current_*
  2. Outside task bc_scheduler_plan_* ,but here you must used task id
3

Oh great, I overlook the first one. Thank you!

Anyway, second one pointing to generated docs is not that useful, I rarely find there usefull information. Descriptions of individual parts are quite often just human readable form of variable names or functions, like:

BC_SCHEDULER_MAX_TASKS
Maximum number of tasks.

or

bc_scheduler_init (void)
Initialize task scheduler

For example, when I was looking for correct version of my humidity tag in http://sdk.bigclown.com/group__bc__tag__humidity.html#ga33227b119c0d2937cad30f18e358c07a I found this:

enum  	bc_tag_humidity_revision_t { 
  BC_TAG_HUMIDITY_REVISION_R1 = 0, 
  BC_TAG_HUMIDITY_REVISION_R2 = 1, 
  BC_TAG_HUMIDITY_REVISION_R3 = 2, 
  BC_TAG_HUMIDITY_REVISION_R4 = 3 
}

When I check revision on physical tag and in your HW repo I see revisions 1.1, 2.1, 3.0, which doesn’t match with your names (is it 3.0 related to BC_TAG_HUMIDITY_REVISION_R4 or BC_TAG_HUMIDITY_REVISION_R3?).

I think that details like this should be also mentioned in docs.

4

It’s true, part sdk has no description. In this time i optimize some parts of sdk, I will try to add the documentation.

It does not matter what more to write about BC_SCHEDULER_MAX_TASKS or bc_scheduler_init. If you like, I like to get inspired.

For tag version, number means major version. Number with minor version means only small change on design or in routing, its not important for working driver.

5

I am not fan of generated docs. The best documentation I used was always written as documents, related to some topic. This allows you to explain lot of thing in context, and what is very important to me, also with examples/code snippets how to use it. I probably learned most by reading examples.

Documentation written in RST/Sphinx for example allows you to combine “hand written” parts with docstrings from function/class definition.

6

Iam understand,
generated documentation is useful, but not suitable for study.

For study I recomend read firmware for kits, I tried to write them as examples.

It is a good idea to convert any of these firmware into documentation and to describe what has been used.

7

Thats will be great! Having such document with real world code examples and comments around will explain a lot of details, like:

  • your FW must have init function, put there any HW setup
  • some of the tags must be initialized with proper version argument
  • how handlers work, what kind of arguments are passed there from scheduler
  • what you need to do to send MQTT message

Beside this basic description some other document or section should be written with description of any differences against basic setup. For example battery module is quite straightforward (init, set handler, set update interval), but climate module seems more complicated (init, handler, individual update and measure on the end).

Thanks a lot.