Commit 950ae89d authored by Rafal Babski's avatar Rafal Babski
Browse files

Merge branch 'doc-update' into 'master'

parents a54c5494 2a2122a1
# 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)
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.
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)
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
----------------------------------------------------