Merge branch 'doc-update' into 'master'

README.md

-# DemoSat project
-
-## Compilation from commandline
-
-## Oscillators and clocks configuration
-
-### Oscillators
-
-| Oscillator | Frequency |
-|------------|-----------|
-| DCO        | 8 MHz     |
-| LFXTCLK    | 32768 Hz  |
-
-### Clocks
-
-| Clock | Source Oscillator | Divider |
-|-------|-------------------|---------|
-| MCLK  | DCO               | 1       |
-| SMCLK | DCO               | 1       |
-| ACLK  | LFXTCLK           | 1       |
-
-### Modules
-
-| Module              | Clock | Divider                  | Description                               |
-|---------------------|-------|--------------------------|-------------------------------------------|
-| FreeRTOS tick timer | ACLK  | 1000                     | FreeRTOS uses this clock for system ticks |
-| UART                | SMCLK | depends on configuration |                                           |
-| I2C                 | SMCLK | 160                      | Standard 100kHz                           |
-| PWM                 | SMCLK | 8 * 4                    | Period 1000                               |
-
-## PIN configuration
-
-| Pins | Function | Connection with                            |
-|------|----------|--------------------------------------------|
-| P1.3 | ADC      | Output of voltage divider near solar panel |
-| P1.4 | PWM      | pin IN A on BD65496MUV                     |
-| P1.5 | GPIO     | pin RES on SDD1306                         |
-| P1.6 | SDA      | pin DIN on SDD1306 and pin SDA on MCP9808  |
-| P1.7 | SCL      | pin CLK on SDD1306 and pin SCL on MCP9808  |
-| P2.0 | UART     | -                                          |
-| P2.1 | UART     | -                                          |
-|------|----------|--------------------------------------------|
-| GND  | Ground   |                                            |
-| VCC  | +3.3V    |                                            |
+MSP430 Demo-Sat project
+=======================
+
+The Demo-Sat project is a CubeSat mock based on [MSP430FR5969 LaunchPad Development Kit](https://www.ti.com/tool/MSP-EXP430FR5969).
+The software was modelled, developed and deployed using [TASTE](https://taste.tools) toolchain.
+
+
+Features
+------------------------------------------------
+
+In order to mimic a Cubesat platform running a basic experiment,
+the following functionality was selected:
+ * Mode management
+ * Power supply monitoring
+ * Thermal management
+ * Command and Control interface based on PUS-C standard
+ * Payload management (using PUS 2 service)
+
+The payload consists of OLED Display to demonstrate on-off and register load commands.
+
+### Modes
+
+![Modes](./doc/img/modes.png)
+
+ * Idle Mode – thermal management is enabled, payload is disabled
+ * Operational Mode – thermal management is enabled, payload is enabled.
+ * Safe Mode – thermal management is disabled, payload is disabled
+
+SW starts in Idle Mode, Observation Mode / Idle Mode can be changed on TC,
+Safe Mode is entered on TC or autonomously on power drop.
+
+### Services
+
+ * PUS 1 - Request Verification
+   - TM\[1,3\] - Successful Start of Execution Verification Report
+   - TM\[1,4\] - Failed Start of Execution Verification Report
+ * PUS 2 - Device Access
+   - TC\[2,1\] - Distribute On/Off Device Commands
+   - TC\[2,2\] - Distribute Register Load Commands
+ * PUS 3 - Housekeeping
+   - TM\[3,25\] - Housekeeping Parameter Report
+ * PUS 222 - Mission Specific
+   - TC\[222,1\] - Switch Mode
+   - TC\[222,11\] - Set Safe Threshold Voltage
+   - TC\[222,21\] - Set Thermal Control Parameters
+
+The services were tailored using [PUS-C Gen](https://indico.esa.int/event/252/contributions/3826/attachments/3040/3692/10_-_Formal_Approach_to_Information_Modelling_PUS-C_and_SRDB.pdf) tool.
+ASN.1/ACN models generated from prepared PUS-C population were imported into TASTE project.
+Tool's population can be found in `pus-c/` directory.
+
+
+Model overview
+------------------------------------------------
+
+Model was created completely in TASTE. It's source files can be found in `demo-sat/` directory.
+
+### Deployment view
+![Deployment View](./doc/img/deployment-view.png)
+
+### Interface view
+![Interface View](./doc/img/interface-view.png)
+
+
+Running software
+------------------------------------------------
+
+### Installation on TASTE VM
+
+0. Prerequisites:
+
+TASTE VM machine with installed: 
+ - `add-ons/install-msp430-gcc.sh`
+ - `add-ons/install-freertos.sh`
+
+ MSP430 device connected and available in TASTE VM (command `ls /dev/ttyACM*` should print `/dev/ttyACM0 /dev/ttyACM1`)
+
+1. Create directory `projects`:
+
+```bash
+cd
+mkdir -p projects
+```
+
+2. Download *msp430-demo-sat* repository:
+
+**TODO** fix link if project to be moved
+
+```bash
+git clone https://gitrepos.estec.esa.int/hcorg/msp430-demo-sat.git
+```
+
+### Building
+
+1. Change directory:
+
+```bash
+cd ~/projects/msp430-demo-sat/demo-sat
+```
+
+2. Build project:
+```bash
+make
+```
+
+After successful compilation the project is ready to run.
+
+### Running project
+
+1. Run linux partition:
+```bash
+cd ~/projects/msp430-demo-sat/demo-sat/work/binaries/
+./run_x86_partition_partition
+```
+
+2. Run gdb_agent_console in new terminal window:
+```bash
+cd /opt/msp430-gcc
+./bin/gdb_agent_console msp430.dat
+```
+
+3. Run msp430 partition in new terminal window:
+```bash
+cd ~/projects/msp430-demo-dat/demo-sat/work/binaries/
+msp430-elf-gdb ./msp430fr5969_partition
+```
+
+In the GDB command line interface:
+```
+target extended-remote :55000
+monitor reset
+load
+continue
+```
+
+In case of any problem with msp430, try following steps:
+* after command `load` try type `si` (step one instruction)
+* if the output address is `0x00000000 in ?? ()` or similar type `load` again.
+
+Here's example gdb session:
+
+```
+GNU gdb (Mitto Systems Limited - msp430-gcc 8.3.0.16) 8.1
+Copyright (C) 2018 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
+and "show warranty" for details.
+This GDB was configured as "--host=x86_64-pc-linux-gnu --target=msp430-elf".
+Type "show configuration" for configuration details.
+For bug reporting instructions, please see:
+<http://www.gnu.org/software/gdb/bugs/>.
+Find the GDB manual and other documentation resources online at:
+<http://www.gnu.org/software/gdb/documentation/>.
+For help, type "help".
+Type "apropos word" to search for commands related to "word"...
+Reading symbols from work/binaries/msp430_partition...done.
+(gdb) target extended-remote :55000
+Remote debugging using :55000
+0x00005326 in __crt0_start ()
+(gdb) monitor reset
+CPU has been reset
+(gdb) load
+Loading section .rodata, size 0x526 lma 0x4400
+Loading section .rodata2, size 0x48 lma 0x4928
+Loading section .persistent, size 0x8bc lma 0x4970
+Loading section .data, size 0xf8 lma 0x522c
+Loading section .upper.data, size 0x2 lma 0x5324
+Loading section .text, size 0xaa6e lma 0x5326
+Loading section __interrupt_vector_46, size 0x2 lma 0xffea
+Loading section __interrupt_vector_47, size 0x2 lma 0xffec
+Loading section __interrupt_vector_49, size 0x2 lma 0xfff0
+Loading section __reset_vector, size 0x2 lma 0xfffe
+Start address 0x5326, load size 47514
+Transfer rate: 9 KB/sec, 3959 bytes/write.
+(gdb) si
+0x00000000 in ?? ()
+(gdb) load
+Loading section .rodata, size 0x526 lma 0x4400
+Loading section .rodata2, size 0x48 lma 0x4928
+Loading section .persistent, size 0x8bc lma 0x4970
+Loading section .data, size 0xf8 lma 0x522c
+Loading section .upper.data, size 0x2 lma 0x5324
+Loading section .text, size 0xaa6e lma 0x5326
+Loading section __interrupt_vector_46, size 0x2 lma 0xffea
+Loading section __interrupt_vector_47, size 0x2 lma 0xffec
+Loading section __interrupt_vector_49, size 0x2 lma 0xfff0
+Loading section __reset_vector, size 0x2 lma 0xfffe
+Start address 0x5326, load size 47514
+Transfer rate: 9 KB/sec, 3959 bytes/write.
+(gdb) si
+0x0000532a in __crt0_init_bss ()
+(gdb) continue
+Continuing.
+```
+
+
+See also
+------------------------------------------------
+ * [Demonstration scenarios](./doc/demonstration.md)
+ * [Hardware documentation](./doc/hardware.md)
+ * [Test scenarios](./doc/test-scenarios.md)

doc/demonstration.md

+MSP430 DemoSat Demonstration Scenarios
+======================================
+
+Mode presentation
+--------------------------------------
+
+The presenter should demonstrate three modes:
+-   Safe Mode -- thermal is disabled, payload is disabled
+-   Idle Mode -- thermal is enabled, payload is disabled
+-   Operational Mode -- thermal is enabled, payload is enabled.
+
+The presenter should demonstrate that manual change of mode may enable
+or disable thermal and payload. At this stage of presentation the
+presenter should show `housekeeping_data`, in particular following
+fields:
+
+-   mode
+-   thermal\_enabled
+-   payload\_enabled
+-   input\_voltage
+
+![Housekeeping](./img/demo-gui-hk.png)
+
+During the presentation the presenter may show field *input\_voltage* on
+the plot.
+
+![Voltage plot](./img/demo-gui-voltage.png)
+
+The presenter should demonstrate the impact of mode management on
+payload and thermal.
+
+This includes automatic mode management and manual mode management.
+
+Presentation scenario:
+
+1.  The presenter should show default mode: *satellite-mode-idle*.
+2.  The presenter should demonstrate PUS-1 failure notification by switching to *satellite-idle-mode*
+3.  The presenter should switch to Operational Mode to show enabled payload
+4.  The presenter should switch to Safe Mode, to present disabled payload and thermal.
+5.  The presenter should try to switch to *satellite-operational-mode* to show PUS-1 failure notification
+6.  The presenter should switch to idle-mode and then to operational-mode
+7.  The presenter should use send `tc_222_11_setSafeThresholdVoltage` with value 1.1 to prepare Demo-Sat to automatic mode management
+8.  The presenter should demonstrate that covering solar panel changes the filed `input_voltage` in housekeeping and if the voltage is below threshold the satellite switches to Safe Mode, which causes disable of payload and thermal management.
+9.  The presenter should demonstrate PUS-1 failure notice after switching mode to Idle Mode when input voltage is below threshold.
+10. After restore of operational input voltage the user should demonstrate that there's no automatic transition from safe-mode.
+
+PUS 1 Success Report:
+
+![PUS 1 Success Report](./img/demo-gui-tc-ok.png)
+
+PUS 1 Failure Report:
+
+![PUS 1 Failure Report](./img/demo-gui-tc-fail.png)
+
+
+
+Thermal presentation
+--------------------------------------
+
+To demonstrate thermal, the Demo-Sat should be in Idle or Operational Mode.
+
+The presenter should show following TM parameters on one plot:
+-   target\_temperature
+-   current\_temperature
+
+![Thermal plots](./img/taste-gui-thermal.png)
+
+1.  The presenter should use telecommand `tc_222_21_setThermalControlParameters` to set thermal control parameters:
+    -   target\_temperature: 40
+    -   kp: 0.3
+    -   ki: 0.2
+2.  The presenter should ensure that the solar panel is exposed to the light
+3.  The presenter should observe the increase of `current_temperature` and after a few moments the `current_temperature` should reach setpoint. Also, the parameter `duty_cycle` should reach their setpoint.
+4.  The presenter should disturb the solar panel to reduce the provided energy, but without changing mode. The `current_temperature` parameter from housekeeping should decrease.
+5.  The presenter can demonstrate another setpoint by changing target temperature to 35.
+6.  The temperature should decrease and after this the `current_temperature` should reach new setpoint.
+
+
+
+Payload
+--------------------------------------
+
+To demonstrate payload the satellite should be in Idle Mode.
+
+During this demonstration, the solar panel should provide sufficient
+level of input voltage.
+
+1.  The presenter should demonstrate the Demo-Sat in Idle Mode and the parameter `payload_enabled` is False and demonstrate PUS-1 failure notification after payload telecommands.
+2.  The presenter should switch satellite into operational mode, the telemetry should report:
+    -   payload\_enabled: True
+    -   payload\_data\_enabled: False
+    -   payload\_data: 0
+3.  The presenter should send `TC_2_1_DistributeOnoffDeviceCommands` telecommand to turn on the OLED. 
+    -   The PUS-1 should report success notification.
+    -   The telemetry parameter `payload_data_enabled` should be True.
+    -   The yellow bar on OLED should be displayed, which denotes that OLED is on.
+4.  The presenter should use `TC_2_2_DistributeRegisterLoadCommands` telecommand to display number on the OLED. 
+    -   The number should be displayed.
+    -   The housekeeping parameter `payload_data` should also show the number from telecommand.
+
+The presenter may present that the drop of input voltage causes shutdown of OLED.

doc/hardware.md

+MSP430 Demo-Sat Hardware
+==========================
+
+## Oscillators and clocks configuration
+
+#### Oscillators
+
+| Oscillator | Frequency |
+|------------|-----------|
+| DCO        | 8 MHz     |
+| LFXTCLK    | 32768 Hz  |
+
+#### Clocks
+
+| Clock | Source Oscillator | Divider |
+|-------|-------------------|---------|
+| MCLK  | DCO               | 1       |
+| SMCLK | DCO               | 1       |
+| ACLK  | LFXTCLK           | 1       |
+
+#### Modules
+
+| Module              | Clock | Divider                  | Description                               |
+|---------------------|-------|--------------------------|-------------------------------------------|
+| FreeRTOS tick timer | ACLK  | 1000                     | FreeRTOS uses this clock for system ticks |
+| UART                | SMCLK | depends on configuration |                                           |
+| I2C                 | SMCLK | 160                      | Standard 100kHz                           |
+| PWM                 | SMCLK | 8 * 4                    | Period 1000                               |
+
+
+## PIN configuration
+
+| Pins | Function | Connection with                            |
+|------|----------|--------------------------------------------|
+| P1.3 | ADC      | Output of voltage divider near solar panel |
+| P1.4 | PWM      | pin IN A on BD65496MUV                     |
+| P1.5 | GPIO     | pin RES on SDD1306                         |
+| P1.6 | SDA      | pin DIN on SDD1306 and pin SDA on MCP9808  |
+| P1.7 | SCL      | pin CLK on SDD1306 and pin SCL on MCP9808  |
+| P2.0 | UART     | -                                          |
+| P2.1 | UART     | -                                          |
+|------|----------|--------------------------------------------|
+| GND  | Ground   |                                            |
+| VCC  | +3.3V    |                                            |
+
+![Pin connection](./img/pin-connection.png)

doc/test-scenarios.md

+MSP430 Demo-Sat Test Scenarios
+==============================
+
+Test to verify Demo-Sat setup (HW + SW). To be executed from TASTE-VM.
+
+
+
+Mode
+----------------------------------------------------
+
+
+### Default mode
+
+After power up the housekeeping data should be:
+-   Housekeeping\_data
+    -   packet\_data: tm\_3\_25\_housekeepingParameterReport
+        -   tm\_3\_25\_housekeepingParameterReport
+            -   housekeepingParameterNotificationNotification
+                -   data hk\_id\_all
+                    -   hk\_id\_all
+                        -   mode: satellite-mode-idle
+                        -   thermal-enabled: True
+                        -   payload-enabled: False
+                        -   input-voltage: *\<non zero value\>*
+                        -   current\_temperature: *\<non zero value\>*
+                        -   target\_temperature: 0.0
+                        -   pi\_integral: -100.0
+                        -   thermal\_duty\_cycle: 0.0
+                        -   payload\_data\_enabled: False
+                        -   payload\_data: 0
+
+
+### Transition from Idle to Safe
+
+Given the reported `satellite-mode` is *satellite-mode-idle* 
+and the `input-voltage` is above the threshold.
+
+When sending telecommand:
+-   packet\_data: tc\_222\_1\_switchMode
+    -   tc\_222\_1\_switchMode
+        -   instructionToSwitchMode
+            -   mode: satellite-mode-safe
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data: tm\_1\_3\_successfulStartOfExecutionVerificationReport
+        -   tm\_1\_3\_successfulStartOfExecutionVerificationReport
+            -   successfulStartOfExecutuinNotificationNotification
+                -   requestId request-id-switch-mode
+
+
+### Transition from Idle to Operational
+
+Given the reported `satellite-mode` is *satellite-mode-idle*
+
+When sending telecommand:
+-   packet\_data: tc\_222\_1\_switchMode
+    -   tc\_222\_1\_switchMode
+        -   instructionToSwitchMode
+            -   mode: satellite-mode-operational
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data: tm\_1\_3\_successfulStartOfExecutionVerificationReport
+        -   tm\_1\_3\_successfulStartOfExecutionVerificationReport
+            -   successfulStartOfExecutuinNotificationNotification
+                -   requestId request-id-switch-mode
+
+
+### Transition from Safe to Idle - Success
+
+Given the reported `satellite-mode` is *satellite-mode-safe*
+and the `input-voltage` is above the threshold
+
+When sending telecommand:
+-   packet\_data: tc\_222\_1\_switchMode
+    -   tc\_222\_1\_switchMode
+        -   instructionToSwitchMode
+            -   mode: satellite-mode-idle
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data:
+        tm\_1\_3\_successfulStartOfExecutionVerificationReport
+        -   tm\_1\_3\_successfulStartOfExecutionVerificationReport
+            -   successfulStartOfExecutuinNotificationNotification
+                -   requestID request-id-switch-mode
+
+### Transition from Safe to Idle - Failure
+
+Given the reported `satellite-mode` is *satellite-mode-safe*
+and the `input-voltage` is below the threshold.
+
+When sending the same telecommand as above.
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data tm\_1\_4\_failedStartOfExecutionVerificationReport
+        -   tm\_1\_4\_failedStartOfExecutuinVerificationReport
+            -   failedStartOfExecutionNotificationNotification
+                -   requestID request-id-switch-mode
+                -   failureNoticeData failure\_notice\_code\_invalid\_mode
+                    -   failure\_notice\_code\_invalid\_mode
+                        -   mode satellite-mode-safe
+                        -   input\_voltage: *\<value bellow voltage threshold\>*
+
+
+### Transition from Safe to Operational
+
+Given the reported `satellite-mode` is *satellite-mode-safe*.
+
+When sending telecommand:
+-   packet\_data: tc\_222\_1\_switchMode
+    -   tc\_222\_1\_switchMode
+        -   instructionToSwitchMode
+            -   mode: satellite-mode-operational
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data tm\_1\_4\_failedStartOfExecutionVerificationReport
+        -   tm\_1\_4\_failedStartOfExecutuinVerificationReport
+            -   failedStartOfExecutionNotificationNotification
+                -   requestID request-id-switch-mode
+                -   failureNoticeData failure\_notice\_code\_invalid\_mode
+                    -   failure\_notice\_code\_invalid\_mode
+                        -   mode satellite-mode-safe
+                        -   input\_voltage: *\<value bellow voltage threshold\>*
+
+
+### Transition from Operational to Idle
+
+Given the reported `satellite-mode` is *satellite-mode-operational*.
+
+When sending telecommand:
+-   packet\_data: tc\_222\_1\_switchMode
+    -   tc\_222\_1\_switchMode
+        -   instructionToSwitchMode
+            -   mode: satellite-mode-idle
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data: tm\_1\_3\_successfulStartOfExecutionVerificationReport
+        -   tm\_1\_3\_successfulStartOfExecutionVerificationReport
+            -   successfulStartOfExecutuinNotificationNotification
+                -   requestId request-id-switch-mode
+
+
+### Transition from Operational to Safe
+
+Given the reported `satellite-mode` is *satellite-mode-operational*.
+
+When sending telecommand:
+-   packet\_data: tc\_222\_1\_switchMode
+    -   tc\_222\_1\_switchMode
+        -   instructionToSwitchMode
+            -   mode: satellite-mode-safe
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data: tm\_1\_3\_successfulStartOfExecutionVerificationReport
+        -   tm\_1\_3\_successfulStartOfExecutionVerificationReport
+            -   successfulStartOfExecutuinNotificationNotification
+                -   requestId request-id-switch-mode
+
+
+### From state to the same state
+
+When the telecommand to switch mode contains the same mode reported by housekeeping, i.e:
+-   packet\_data: tc\_222\_1\_switchMode
+    -   tc\_222\_1\_switchMode
+        -   instructionToSwitchMode
+            -   mode: \<mode from telemetry\>
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data tm\_1\_4\_failedStartOfExecutionVerificationReport
+        -   tm\_1\_4\_failedStartOfExecutuinVerificationReport
+            -   failedStartOfExecutionNotificationNotification
+                -   requestID request-id-switch-mode
+                -   failureNoticeData failure\_notice\_code\_invalid\_mode
+                    -   failure\_notice\_code\_invalid\_mode
+                        -   mode \<mode from telemetry\>
+                        -   input\_voltage: \<non zero value\>
+
+
+
+Voltage
+----------------------------------------------------
+
+### Set safe threshold voltage
+
+When the telecommand:
+-   command
+    -   packet\_data tc\_222\_11\_setSafeThresholdVoltage
+        -   tc\_222\_11\_setSafeThresholdVoltage
+            -   instructionToSetSafeThresholdVoltage
+                -   threshold\_voltage 2V
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data tm\_1\_3\_successfulStartOfExecutionVerificationReport
+        -   tm\_1\_3\_successfulStartOfExecutionVerificationReport
+            -   successfullStartOfExecutionNotificationNotification
+                -   requestId request-id-set-threshold-voltage
+                    -   failure\_notice\_code\_invalid\_mode
+                        -   mode \<mode from telemetry\>
+                        -   input\_voltage: \<small value\>
+
+
+
+Thermal
+----------------------------------------------------
+
+### Set thermal control parameters
+
+When the telecommand is:
+-   command
+    -   packet\_data tc\_222\_21\_setThermalControlParameters
+        -   c\_222\_21\_setThermalControlParameters
+            -   instructionToSetThermalControlParameters
+                -   target\_temperature 35.0
+                -   kp 0.3
+                -   ki 0.2
+
+Then the PUS-1 report should be:
+-   report
+    -   packet\_data tm\_1\_3\_successfulStartOfExecutionVerificationReport
+        -   tm\_1\_3\_successfulStartOfExecutionVerificationReport
+            -   successfulStartOfExecutionNotificationNotification
+                -   requestID request-id-set-thermal-control-parameters
+
+
+
+Payload
+----------------------------------------------------