Firmware: Missing Document

[bryn51]

The firmware section contains lots of information how to update and edit the firmware, and update the bootloader. I feel it would be useful to have a document that ties it all together, also adds some guides on actually making changes to the code.

• What coding style to use. Emphasis on insertion of comments
• What conventions about making changes then sending them back to the github repository. (i.e. communication with SC team). You cannot just push up a set of changes to the main repository on Github, so what procedure needs to be followed.?
• Separate installation of Bootloader info from Firmware update info (i.e. separate files) because its confusing to have them in together (because both of them are technically firmware). Include a memory map diagram of the MCU showing Bootloader and User Firmware code areas to make the distinction clear. Loading of Bootloader is rarely going to be necessary, unless the user did something to trash it. Why would a SC user ever need to make changes to bootloader ? Is the user going to try to replace bootloader code because the SC does not seem to be functional? What is a simple test to establish if bootloader replacement is needed ?
• Rearrange the editing the firmware file to add a top level list of tasks to perform in an enumerated list, in the logical order in which things need to be done. For example, the cloning of the repository needs to happen before you can CD into the directory and run commands.
• There needs to be some guidance added on having (a) a local clone of the master repository (which will always be a fork); and (b) a local clone of the fork used for direct editing and debugging. Where is the best place to put the local copy ?
• Provide guidance on actions to be taken when code is ready to be merged with the master.
• A list of functions performed by each part of the firmware with a middle level of detail e.g.
• • (sam) reading urban board connected sensors (Serial, I2S, I2C)
• • (sam) fetch readings from I2C devices including PM Board.
• • (sam) write to non sensor devices (such as OLED);
• • (sam) monitor button states and operate LED signals.
• • (sam) Compile readings into a JSON file, send to ESP comms device.
• • (sam) Store readings onto SD Card.
• • (sam) Respond to commands via USB (CLI).
• • (sam) At startup, determine connected sensors.
• • (esp) provide Wi-Fi Host port, HTML Server
• • (esp) record User initialization settings.
• • (esp) deliver initialization settings to SAM when requested.
• • (esp) Manage connection to central server via MQTT.
• • (esp) Send readings to central server via Wi-Fi at configured time intervals.
• • (PM) Operate as a I2C slave device responding to SAM as master.
• • (PM) Manage connections to serial devices (PM1 & PM2, Wind, Rain, Temp, others).
• • (PM) Fetch readings from serial devices.
• • (PM) send readings when requested by Master device (sam).
    ....
• Add a functional block schematic diagram of the main parts of the system, showing things like MCU's, Sensors, SD, Wiring, Power connections.