Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

103 change readme composition and add more information about running #164

Merged
merged 12 commits into from
Nov 21, 2024
Merged

103 change readme composition and add more information about running #164

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
b4277d7
First draft of new README for front page
asgibson Sep 18, 2024
e072bda
Fixes
asgibson Sep 18, 2024
2657717
span did not work for color, attempting to use font
asgibson Sep 18, 2024
67553c8
Still no color. Attempting Latex style
asgibson Sep 18, 2024
62b88e5
Switch to pure "blue"
asgibson Sep 18, 2024
6bc54a9
Trying for better colorization of OnAIR in text.
asgibson Sep 19, 2024
fb54669
Updates for docs
asgibson Nov 18, 2024
7bdf5bb
Added images dir and pipeline flow pic
asgibson Nov 18, 2024
2420865
Updates for clarity, content and comparibility
asgibson Nov 18, 2024
620c6f4
Fixed one multi-line paragraph
asgibson Nov 18, 2024
9426438
Pointed Timestamp in CSV to parse utility method
asgibson Nov 19, 2024
2b15957
Added license badge with link and linked unit test badge to actions
asgibson Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
241 changes: 74 additions & 167 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,206 +1,109 @@
![Build](https://github.com/nasa/OnAIR/actions/workflows/unit-test.yml/badge.svg)
![Python Versions](https://img.shields.io/badge/python-3.8%20|%203.9%20|%203.10%20|%203.11%20|%203.12-blue.svg)
![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)
[![GitHub License](https://img.shields.io/badge/License-NOSA-green)](https://github.com/nasa/OnAIR/blob/main/NOSA%20GSC-19165-1%20OnAIR.pdf)
[![Build](https://github.com/nasa/OnAIR/actions/workflows/unit-test.yml/badge.svg)](https://github.com/nasa/OnAIR/actions)
[![CodeCov](https://codecov.io/gh/nasa/OnAIR/branch/main/graph/badge.svg?token=L0WVOTD5X9)](https://codecov.io/gh/nasa/OnAIR)

![alt text](OnAIR_logo.svg "The OnAIR logo, italicized NASA worm style font in blue and orange")
![alt text](doc/images/OnAIR_logo.svg "The OnAIR logo, italicized NASA worm style font in blue and orange")

# The On-board Artificial Intelligence Research (OnAIR) Platform

The On-board Artificial Intelligence Research (OnAIR) Platform is a framework that enables AI algorithms written in Python to interact with NASA's [cFS](https://github.com/nasa/cFS).
It is intended to explore research concepts in autonomous operations in a simulated environment.
Featuring a plugin style architechture, it is designed to facilitate rapid prototyping of cognitive agents.

## Generating environment
## Key Features

Create a conda environment with the necessary packages
- Python-based AI algorithm support
- Configurable to use different data source types
- Core Flight System (cFS)
- CSV file
- Redis
- Adaptable to new data source types
- Selectable at runtime
- Set your own data source
- Cognitive architechture based data pipeline
- Knowledge Representations
- Learners
- Planners
- Complex Reasoners
- Flexible plugin system for cognitive components

conda env create -f environment.yml
## Quick Start

## Redis example
**NOTE:** You may need to put your specific python or version in place of `python`, e.g., `python3.12`

Using the redis_adapter.py as the DataSource, telemetry can be received through multiple Redis channels and inserted into the full data frame.
**NOTE:** You may need the `-m` option to run python modules, e.g., `python -m coverage report`

### OnAIR config file (.ini)

The redis_example.ini uses a very basic setup:
- meta : redis_example_CONFIG.json
- parser : onair/data_handling/redis_adapter.py
- plugins : one of each type, all of them 'generic' that do nothing

### Telemetry config file (.json)

The telemetry file defines the subscribed channels, data frame and subsystems.
- subscriptions : defines channel names where telemetry will be received
- order : designation of where each 'channel.telemetry_item' is to be put in full data frame (the data header)
- subsystems : data for each specific telemetry item (descriptions only for redis example)


### Receipt of telemetry

The Redis adapter expects any published telemetry on a channel to include:
- time
- every telemetry_item as described under "order" as 'channel.telemetry_item'

All messages sent must be json format (key to value) and will warn when it is not then discard the message (outputting what was received first). Keys should match the required telemetry_item names with the addition of "time." Values should be floats.
### 1. Clone the repository:
```
git clone https://github.com/nasa/OnAIR.git
cd OnAIR
```
Gets the repository and enters the directory.

### Running the example
### 2. Set up the environment:
Using your local Python installation (your `pip` command may vary, e.g., `pip3.12`)
```
pip install -r requirements.txt
```
the-other-james marked this conversation as resolved.
Show resolved Hide resolved
This installs the packages necessary for testing and running.

If not already running, start a Redis server on 'localhost', port:6379 (typical defaults)
### 3. Run the unit tests and check the coverage:
NOTE: this step is technically optional, but highly recommended.
```
redis-server
python driver.py -t
coverage report
```
If all tests pass and coverage is shown to be at 100%, your setup is likely able to use OnAIR.

Start up OnAIR with the redis_example.ini file:
### 4. Run the default configuration for OnAIR:
```
python driver.py onair/config/redis_example.ini
python driver.py
```
You should see:
Output should begin. It will probably be very fast, but should look similar to:
```
Redis Adapter ignoring file

---- Redis adapter connecting to server...

---- ... connected!

---- Subscribing to channel: state_0

---- Subscribing to channel: state_1

---- Subscribing to channel: state_2

---- Redis adapter: channel 'state_0' received message type: subscribe.

---- Redis adapter: channel 'state_1' received message type: subscribe.

---- Redis adapter: channel 'state_2' received message type: subscribe.

***************************************************
************ SIMULATION STARTED ************
***************************************************
```

In another process run the experimental publisher:
```
python redis-experiment-publisher.py
```
This will send telemetry every 2 seconds, one channel at random until all 3 channels have recieved data then repeat for a total of 9 times (all of which can be changed in the file). Its output should be similar to this:
```
Published data to state_0, [0, 0.1, 0.2]
Published data to state_1, [1, 1.1, 1.2]
Published data to state_2, [2, 2.1, 2.2]
Completed 1 loops
Published data to state_2, [3, 3.1, 3.2]
Published data to state_1, [4, 4.1, 4.2]
```
And OnAir should begin receiving data similarly to this:
```
--------------------- STEP 1 ---------------------

CURRENT DATA: [0, 0.1, 0.2, '-', '-', '-', '-']
CURRENT DATA: [946706400.0, 13.0, 3.0, 0.0, 2000.0, 0.0, 34.29, 0.0, 0.0]
INTERPRETED SYSTEM STATUS: ---

--------------------- STEP 2 ---------------------

CURRENT DATA: [1, 0.1, 0.2, 1.1, 1.2, '-', '-']
INTERPRETED SYSTEM STATUS: ---

--------------------- STEP 3 ---------------------

CURRENT DATA: [2, 0.1, 0.2, 1.1, 1.2, 2.1, 2.2]
INTERPRETED SYSTEM STATUS: ---

--------------------- STEP 4 ---------------------

CURRENT DATA: [3, 0.1, 0.2, 1.1, 1.2, 3.1, 3.2]
INTERPRETED SYSTEM STATUS: ---

--------------------- STEP 5 ---------------------

CURRENT DATA: [4, 0.1, 0.2, 4.1, 4.2, 3.1, 3.2]
INTERPRETED SYSTEM STATUS: ---
```

## Running unit tests

Instructions on how to run unit tests for OnAIR

### Required python installs:
pytest,
pytest-mock,
coverage

### Optional python install:
pytest-randomly

### Running the unit tests from the driver.py file

From the parent directory of your local repository:
```
python driver.py -t
...
```
--------------------- STEP 1439 ---------------------

#### A few optional settings for the driver.py file
Options that may be added to the driver.py test run. Use these at your own discretion.

`--conftest-seed=###` - set the random values seed for this run
`--randomly-seed=###` - set the random order seed for this run
`--verbose` or `-v` - set verbosity level, also -vv, -vvv, etc.
`-k KEYWORD` - only run tests that match the KEYWORD (see `pytest --help`)

NOTE: Running tests will output results using provided seeds, but each seed is random when not set directly.
Example start of test output:
```
Using --conftest-seed=1691289424
===== test session starts =======
platform linux -- Python 3.11.2, pytest-7.2.0, pluggy-1.3.0
Using --randomly-seed=1956010105
```
Copy and paste previously output seeds (or type them out) as the arguments to repeat results.
CURRENT DATA: [946707838.0, 30.0, 12.0, 200.0, 0.0, 0.0, 182.1, 0.0, 1.0]
INTERPRETED SYSTEM STATUS: ---

### Running pytest directly from command line
--------------------- STEP 1440 ---------------------

For the equivalent of the driver.py run:
```
python -m coverage run --branch --source=onair,plugins -m pytest ./test/
CURRENT DATA: [946707839.0, 30.0, 12.0, 200.0, 0.0, 0.0, 182.28, 0.0, 1.0]
INTERPRETED SYSTEM STATUS: ---
```

#### Command breakdown:

`python -m` - invokes the python runtime on the library following the -m
`coverage run` - runs coverage data collection during testing, wrapping itself on the test runner used
`--branch` - includes code branching information in the coverage report
`--source=onair,plugins` - tells coverage where the code under test exists for reporting line hits
`-m pytest` - tells coverage what test runner (framework) to wrap
`./test` - run all tests found in this directory and subdirectories

#### A few optional settings for the command line
Options that may be added to the command line test run. Use these at your own discretion.

`--disable-warnings` - removes the warning reports, but displays count (i.e., 124 passed, 1 warning in 0.65s)
`-p no:randomly` - ONLY required to stop random order testing IFF pytest-randomly installed
`--conftest-seed=###` - set the random values seed for this run
`--randomly-seed=###` - set the random order seed for this run
`--verbose` or `-v` - set verbosity level, also -vv, -vvv, etc.
`-k KEYWORD` - only run tests that match the KEYWORD (see `pytest --help`)

NOTE: see note about seeds in driver.py section above

### To view testing line coverage after run:
NOTE: you may or may not need the `python -m` to run coverage report or html

`coverage report` - prints basic results in terminal
or
`coverage html` - creates htmlcov/index.html, automatic when using driver.py for testing

then
`<browser_here> htmlcov/index.html` - browsable coverage (i.e., `firefox htmlcov/index.html`)

## Running with Core Flight System (cFS)
OnAIR can be setup to subscribe to and recieve messages from cFS. For more information see [doc/cfs-onair-guide.md](doc/cfs-onair-guide.md)

## License and Copyright

Please refer to [NOSA GSC-19165-1 OnAIR.pdf](NOSA%20GSC-19165-1%20OnAIR.pdf) and [COPYRIGHT](COPYRIGHT).

## Contributions
At this point it should stop.
This default used a CSV file as the data source and stops at end of file.
The configuration file used is [default_config.ini](onair/config/default_config.ini).
When this runs without errors, your basic setup is complete.

### 5. Next steps:
#### [Documents and Guides](doc/README.md)
the-other-james marked this conversation as resolved.
Show resolved Hide resolved
Information on how OnAIR is set up and operates.
#### [Initialization Files](onair/config)
Examples of how to configure OnAIR for use.
#### [Telemetry Definition Files](onair/data/telemetry_configs)
Example setup files for describing the pipeline's data frame.
#### [Plugins](plugins)
The provided cognitive components.
#### [Data Sources](onair/data_handling)
Provided data handling for telemetry input.

## Contributing

Please open an issue if you find any problems.
We are a small team, but will try to respond in a timely fashion.
Expand All @@ -214,3 +117,7 @@ Next, please create an issue for the fix or feature and note that you intend to
Fork the repository and create a branch with a name that starts with the issue number.
Once done, submit your pull request and we'll take a look.
You may want to make draft pull requests to solicit feedback on larger changes.

## License and Copyright

Please refer to [NOSA GSC-19165-1 OnAIR.pdf](NOSA%20GSC-19165-1%20OnAIR.pdf) and [COPYRIGHT](COPYRIGHT).
2 changes: 1 addition & 1 deletion doc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
![alt text](../OnAIR_logo.svg "The OnAIR logo, italicized NASA worm style font in blue and orange")
![alt text](images/OnAIR_logo.svg "The OnAIR logo, italicized NASA worm style font in blue and orange")

# Documents and Guides

Expand Down
Loading
Loading