This is a shell utility to manage Cognicept tools.
You need:
openssh-server : (Optional) in order to enable terminal function for KriyaInstall:
sudo apt-get install python3 python3-pip
To install the package locally, run:
pip3 install -e <path-to-the-repo>
To install from Python Package Index (PyPI), run:
pip3 install cognicept-shell
To verify installation, try to run
cognicept -h
If you get cognicept: command not found error, make sure that ~/.local/bin/ is in your $PATH. You could run this:
export PATH=$PATH:/home/$USER/.local/bin/
and add it to your .bashrc file.
To set-up autcomplete when using the cognicept shell, run:
cognicept config --autocomplete
Restart the terminal and autocomplete should be functioning
This will setup python argcomplete globally and may affect other packages. If argcomplete has been setup globally for other project, this setup is not required.
This command essentially calls the function activate-global-python-argcomplete
More information about this can be found in https://pypi.org/project/argcomplete/#activating-global-completion
For details on usage, use
cognicept -h
config: Configure Cognicept toolscognicept-shell and Cognicept agents are configured in runtime.env file typically placed in ~/.cognicept/runtime.env. The file defines the docker environment used by the Cognicept agents.
This command allows to inspect and modify the configuration file. You can use parameter --path to modify the path to the Cognicept config directory.
To print full configuration, run:
cognicept config --read
To add new configuration parameter (or modify single value), run:
cognicept config --add
Variables used by cognicept-shell:
COGNICEPT_ACCESS_KEYCOGNICEPT_API_URICOGNICEPT_USER_API_URICOG_AGENT_CONTAINERSCOG_AGENT_IMAGESCOG_EXTRA_IMAGES : images to pull from Cognicept and general docker image repositoriesAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN: temporary AWS credentials modified by keyrotate and needed for updateCOG_ENABLE_SSHCOG_ENABLE_SSH_KEY_AUTHCOG_ENABLE_AUTOMATIC_SSHCOG_SSH_DEFAULT_USERTo setup ssh access from remote_intervention_agent to the host machine, run:
cognicept config --ssh
It will generate ssh keys in ~/.cognicept/ssh/ and configures COG_ENABLE_SSH, COG_ENABLE_SSH_KEY_AUTH, COG_ENABLE_AUTOMATIC_SSH, COG_SSH_DEFAULT_USER according to the user preferences. If COG_ENABLE_AUTOMATIC_SSH is enabled, public key is copied into ~/.ssh/authorized_hosts; sudo access is requested to perform this action.
To setup autocomplete from cognicept shell, run:
cognicept config --auto
status: Get status of Cognicept agentscognicept status
Prints status of agents and other containers managed by cognicept-shell. Possible values:
version: Display Cognicept Shell and Container versioncognicept version
Prints the version of current cognicept shell and other containers version
update: Update Cognicept toolsUpdates images for agents and tools specified in COG_AGENT_IMAGES and COG_EXTRA_IMAGES config variables. It requires temporary credentials to be valid. If the available disk space is less than 3 GB, the update will not proceed. This check ensures that there is sufficient space for the update to run successfully. For updates to take effect, containers need to be restarted with restart command.
To run update in detached mode:
cognicept update -d
In detached mode, printing of update statuses in muted. Update is run in a seperate process. Update will continue to run even if terminal session is closed.
To update docker images in environment variable COGNICEPT_EXTRA_IMAGES
cognicept update --image <docker-images-repo>
To override the disk space check before pulling images:
cognicept update -s
the disk space check will be bypassed, and the update will proceed regardless of the available disk space
By default, cognicept update doe not update the config, to update the config run
cognicept update --configuration
This will update the configs wihout updating the agents
lastevent: Display last event log reported by Cognicept agentDisplays last event saved by cgs_diagnostics_agent from ~/.cognicept/logs.
start/stop/restart: start/stop/restart cognicept agentsThese commands are used to start/stop/restart containers specified in COG_AGENT_CONTAINERS/COG_AGENT_IMAGES. Certain container names are reserved for Cognicept agents and are preconfigured:
cgs_diagnostics_agentremote_intervention_agentkriya_watchdogcgs_diagnostics_ecs_apicgs_diagnostics_streamer_apicgs_bagger_serverhealth_aggregatordiagnostics_aggregatorkopilotsmartplus_soundmap_managercomputer_health_metricsslamtec_adaptercam_captureAny agent name or image type can be put in the list as long as default command for the image is specified. All containers are started in host network mode.
Following are examples for using start. stop follows same API as start. restart first calls stop and then stop .
To start all listed agents COG_AGENT_CONTAINERS don't specify any argument:
cognicept start
To start all agents:
cognicept start --agents
To start specific agents:
cognicept start remote_intervention_agent cgs_diagnostics_agent
To run restart in detached mode:
cognicept restart -d
Detached mode is particularly useful for restarting a cognicept agent remotely. In detached mode, progress of restart will not printed.
To restart and clearing logs
cognicept restart --prune
keyrotate: Rotate Cognicept cloud keysUpdates temporary AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) using COGNICEPT_ACCESS_KEY from COGNICEPT_API_URI. The validity of the credentials is 12 hours. Internet access with HTTPS allowed is needed.
record: Manage rosbag recording session to start/stop/pause/resume/get status/record all topicsThese commands are used to start/stop/pause/resume/get status/record all topics in a rosbag. All the operations are done by running an exec command inside the cgs_bagger_server container. All bags are typically placed in the bags folder of the Cognicept configuration directory: ~/.cognicept/bags/
To start start a recording session list all topics to be recorded separated by a space and with their / prefix:
cognicept record --start /odom /cmd_vel /rosout_agg /tf /tf_static
To record ALL topics use --all:
NOTE: rosbags tend to become quite big quite fast especially if there are camera topics. If there is less than 1 GB disk space, the recording self terminates.
cognicept record --all
To stop a recording session:
cognicept record --stop
Alternatively, the latest bag recording can be stopped and automatically pushed to the Cognicept cloud with a single command by providing autopush value:
cognicept record --stop autopush
To pause a recording session:
cognicept record --pause
To resume a recording session:
cognicept record --resume
To get the status of the current recording:
cognicept record --status
Status can be Ready, Started, Stopped, Paused and Resumed.
NOTE: A note on the retry mechanisms built in to improve reliability. If the retry mechanism fails, both cognicept record --start and cognicept record --all will automatically restart the cgs_bagger_server. A new recording session needs to be started if this happens. All other commands will just inform that the retry has failed since these are not essential operations for bag recording.
push: Push data to Cognicept cloudThese commands are used to push data on to the Cognicept cloud.
To push a bag file, specify the name of the bag file:
cognicept push --bag sample_recording.bag
NOTE: Only bags in the dedicated Cognicept configuration bags directory, usually ~/.cognicept/bags, will be detected and uploaded. Bag files in any other location need to be moved to this directory before upload. Bag files generated using the cognicept record feature will be automatically placed in the Cognicept configuration bags directory.
As a shorthand, you can push the latest bag file recording by not specifying any argument. This will automatically look for the latest bag file by create time and upload it:
cognicept push --bag
init: Initiates the runtime.env file with values from the COGNICEPT_USER_API_URITo initiate a runtime.env file, specify the robot id and organisation id and then provide credentials when prompted
cognicept init --robot_id sample_robot --org_id sample_org
Username: sample_username
Password: sample_password (masked)
is supported in version 1.6 for cognicept-shell command below:
cognicept update/version/start/stop/restart
To make it work, you should added an enviroment variable COG_COMPOSE_FILE in ~/.cognicept/runtime.env and specific the file directory of the docker-compose.yaml file, eg
COG_COMPOSE_FILE=~/.cognicept/docker-compose.yaml
Sample of docker-compose file:
version: "3.9"
services:
service_name:
container_name: service_name
network_mode: "host"
restart: unless-stopped
env_file:
- ${HOME}/.cognicept/runtime.env
image: image_repo
command: python3 example.py
Sample response after running cognicept version
Cognicept Shell Version 1.6.0
+------------------------------+-----------+----------------+
| Container Name | Version | Version Tags |
|------------------------------+-----------+----------------|
| remote_intervention_agent | latest | latest |
| kriya_watchdog | latest | latest |
| cgs_diagnostics_ecs_api | dev | latest |
| cgs_diagnostics_streamer_api | dev | latest |
| cgs_diagnostics_agent | dev | latest |
| service_name | | |
+------------------------------+-----------+----------------+
Runtime enviroment file directory: ~/.cognicept/
move: to move a robot from one organisation to anotherThe `cognicept move`` command allows you to move a robot to a different organization with the following flags:
--robot_id: Specify the desired robot_id.--old_org_id: Provide the organization id where the robot is currently residing.--new_org_id: Indicate the target organization id to which you want to move the robot.--skip: You can use this flag to specify if you want to skip the moving of any of the following robot data:
map: Skip moving the map data.schedule: Skip moving the schedule data.waypoint: Skip moving the waypoint data.Example (without skip):
cognicept move --robot_id=<robot_id> --old_org_id=<old_org_id> --new_org_id=<new_org_id>
This command will move the specified robot to the new organization without skipping any data.
Example (with skip):
cognicept move --robot_id=<robot_id> --old_org_id=<old_org_id> --new_org_id=<new_org_id> --skip waypoint map
This command will move the robot while skipping the move map and waypoint
After moving the robot to the new organization, there are additional steps required to get the robot online. Follow these steps:
Navigate to the terminal connected to the robot.
Run the following command, replacing <new org id> and <new robot id> with the actual values displayed after running cognicept move:
cognicept init --org_id <new org id> --robot_id <new robot id>
This command updates the runtime.env configuration file inside the robot with its new robot_code, site_code, agent_id, cognicept_access_key, and aws_webrtc_channel_arn.
Run the cognicept keyrotate command.
Run the cognicept restart command. Note: by default it is restart in detach mode.
After completing these steps, wait for a few minutes, and the robot should be online in the new organization.
autoupdater: to pull the auto update server and start the servicescognicept autoupdater --pull update the OTA server to latest version
cognicept autoupdater --setup Copy service file, setup and start the systemd service
(RECOMMENDED) build and run the tests in Docker by running the commands below:
To test in Ubuntu 20.04 bash run_tests_ubuntu_20.sh
To test in Ubuntu 22.04 bash run_tests_ubuntu_22.sh
Alternatively, you can test locally
cognicept-shell is using pytest as the test framework. Make sure you install manually:
pip3 install pytest pytest-cov cli_test_helpers mock
To run tests, execute:
# Run tests natively.
pytest --cov=cogniceptshell tests
Output will look like this:
user@computer:~/Desktop/repo/cognicept-shell$ pytest --cov=cogniceptshell tests
============================================ test session starts =============================================
platform linux -- Python 3.8.19, pytest-6.1.1, py-1.9.0, pluggy-0.13.1
rootdir: /
plugins: mock-3.12.0, cov-2.10.1
collected 165 items
tests/functional/test_config.py .........s..... [ 9%]
tests/functional/test_disk_space.py . [ 9%]
tests/functional/test_move.py ........ [ 14%]
tests/functional/test_push.py .......... [ 20%]
tests/functional/test_record.py .......... [ 26%]
tests/unit/test_config.py ................ [ 36%]
tests/unit/test_get_disk_space.py . [ 36%]
tests/unit/test_get_robot_org_id.py ...... [ 40%]
tests/unit/test_keyrotate.py ... [ 42%]
tests/unit/test_lifecycle.py ............................. [ 60%]
tests/unit/test_move.py .................................................. [ 90%]
tests/unit/test_populate_config_files.py .... [ 92%]
tests/unit/test_pull_config_templates.py ... [ 94%]
tests/unit/test_update_event_log.py ...... [ 98%]
tests/unit/test_version_update.py ... [100%]
================================== 164 passed, 1 skipped in 114.72s (0:01:54) ================================
To build the PyPI package, run:
python3 setup.py sdist bdist_wheel
This will generate the build files.
To upload the dev package, run:
python3 -m twine upload --repository testpypi dist/* --verbose
To upload the prod package, run:
python3 -m twine upload dist/* --verbose
Please follow the successful branching model. The naming of branches follows:
1.8.0 [19/09/2024]
enabled key in the agent configuration file. When set to true, the specified agent will not load in the Cognicept shell.1.7.6 [01/07/2024]
1.7.5 [26/06/2024]
1.7.4 [18/06/2024]
1.7.3 [12/06/2024]
1.7.2[23/04/2024]
1.7.1[24/11/2023]
1.7.0[25/10/2023]
cognicept update check for remaining disk space (in root directory) before pulling each imagecognicept update -s overrides check for disk space before pulling imagescognicept update will update the success or failure to S+ event logscognicept version will display the latest version of the docker imagescognicept restart by default is restarting in detached modecognicept restart -a to restart in attached modecognicept init support --robot_code and --org_codecognicept move feature1.6.1[22/5/2023]
cognicept update prompts the user before upgrading the cognicept-shell versioncognicept update -y will upgrade cognicept-shell directlycognicept init bug for non-existing robot_id and org_idwebsocket-client, paramiko dependencies1.6 [12/5/2023]
cognicept update/version/start/stop/restart support of docker-compose with enviroment variable COG_COMPOSE_FILEcognicept restart --prune for clearing logscognicept update --image to update docker images in environment variable COGNICEPT_EXTRA_IMAGEScognicept update will prompts msgs for users about the specific errors faced when trying to run cognicept update1.5 [23/9/2022]
cognicept update1.4 [16/12/2021]
init commandversion command to display agent version1.3 [21/10/2021]
1.2 [29/6/2021]
1.1 []
1.0.3 []
1.0 [15/12/2020]
start commandCOGNICEPT_ACCESS_KEYkeyrotate commandrecord and push commands for management of rosbagslastevent command to read last eventremote_intervention_agent0.1 [10/6/2020]
FAQs
Shell utility to configure Cognicept tools.
We found that cognicept-shell demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.