{"id":18552352,"url":"https://github.com/cuspaceflight/cusf-messaging","last_synced_at":"2025-05-15T11:12:32.174Z","repository":{"id":89145334,"uuid":"61807384","full_name":"cuspaceflight/cusf-messaging","owner":"cuspaceflight","description":"A messaging system allowing seamless inter and intra board communication between embedded software components","archived":false,"fork":false,"pushed_at":"2017-09-01T13:09:06.000Z","size":137,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-17T10:49:04.796Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuspaceflight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-23T13:29:45.000Z","updated_at":"2019-03-27T11:15:47.000Z","dependencies_parsed_at":"2023-03-15T04:00:48.329Z","dependency_job_id":null,"html_url":"https://github.com/cuspaceflight/cusf-messaging","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuspaceflight%2Fcusf-messaging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuspaceflight%2Fcusf-messaging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuspaceflight%2Fcusf-messaging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuspaceflight%2Fcusf-messaging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuspaceflight","download_url":"https://codeload.github.com/cuspaceflight/cusf-messaging/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328389,"owners_count":22052633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T21:13:56.059Z","updated_at":"2025-05-15T11:12:27.166Z","avatar_url":"https://github.com/cuspaceflight.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cusf-messaging\nA messaging system allowing seamless inter and intra board communication between software components. \n\n## Installation\n\nSee [Spalax](https://github.com/cuspaceflight/spalax) for an example of how to integrate with your project.\n\n## Configuration\n\nThe config directory contains a number of files that are used to configure the various packet assignments, etc...\n\n- [avionics_config.h](include/config/avionics_config.h): contains a struct declaration that must be defined somewhere in your executable - see [INSTALL.md](INSTALL.md) for more info\n\n- [component_state_config.h](include/config/component_state_config.h): contains the avionics components to be tracked by the Component State component\n\n- [messaging_config.h](include/config/messaging_config.h): defines the meaning of the various message metadata bits\n\n- [telemetry_config.h](include/config/telemetry_config.h): defines the various packet origins along with various packet ids (TELEMETRY_ID). It also defines various telemetry sources (TELEMETRY_SOURCE) which group together various packet ids.\n\n## Components\n\nThe library contains a number of components which users can mix and match as required. It is reccomended you read [INSTALL.md](INSTALL.md) before trying to get the library to work in your project.\n\n### Telemetry Component\n\nA variable sized packet system, complete with an allocator system that facilitates allocating said packets from statically allocated buffers.\n\nTo create a telemetry allocator, use the following macro within a source file.\n\n```c\nTELEMETRY_ALLOCATOR(allocator_name, heap_size);\n```\n\nwhere allocator_name is the name to give the static variable and heap_size is the number of bytes storage to allocate.\n\nBefore you use the allocator you must call\n\n```c\ntelemetry_allocator_init(\u0026allocator_name);\n```\n\nYou can then allocate a packet using\n\n```c\ntelemetry_t* packet = telemetry_allocator_alloc(\u0026allocator_name, payload_size);\n```\n\nwhere payload_size is the size of the desired packets payload.\n\nAllocated packets are freed using the following\n\n```c\ntelemetry_allocator_free(packet);\n```\n\n\n### Messaging Component\n\nThe messaging component builds on top of the Telemetry Component to provide seamless inter and intra board communication between software components.\n\nMessages are produced by messaging producers and consumed by messaging consumers without any coupling between the two.\n\n#### Producer\n\nA messaging producer is defined using\n\n```c\nMESSAGING_PRODUCER(producer_name, packet_id, payload_size, max_num_packets);\n```\n\nwhere:\n- producer_name is the name to give the static variable\n- packet_id is the id of the packet to allocate\n- payload_size is the size of the packet's payload\n- max_num_packets is the maximum number of packets that can be in existance in the messaging system at once\n\nA small number (~15) should be sufficient for max_num_packets in all but the most high data rate (~1kHz) situations.\n\nBefore using the producer one must call\n\n```c\nmessaging_producer_init(\u0026producer_name);\n```\n\nOne can then send data with\n\n```c\nmessaging_producer_send(\u0026producer_name, message_metadata, data);\n```\n\nWhere message_metadata is for filtering (discussed later) and data is the data to send. The contents of data are copied by the messaging system and so the memory can be freed/reused after this call.\n\n#### Consumer\n\nA messaging consumer is declared using\n\n```c\nMESSAGING_CONSUMER(consumer_name, packet_source, packet_source_mask, message_metadata, message_metadata_mask, consumer_func, mailbox_size)\n```\n\nwhere:\n\n- consumer_name is the name of the static variable\n- packet_source is the packet source to receive packets from\n- packet_source_mask is the packet source mask to receive packets from (specifies which bits of a packet's id to compare for equality with packet_source)\n- message_metadata specifies the desired packet metadata to receive packets matching\n- message_metadata_mask specifies the packet metadata bits to compare for equality with message_metadata\n- consumer_func is the consumer function (see later)\n- mailbox_size is the maximum number of packets that can be enqueued to this consumer\n\nFor most applicaations message_metadata and message_metatadata_mask can both be 0 - i.e. don't perform any metadata based filtering. They are currently only used to limit high data rate producers from swamping USB and CAN connections.\n\nA small number (~15) should be sufficient for mailbox_size in all but the most high data rate (~1kHz) situations.\n\nAs before this must be initialized before it can be used using \n\n```c\nmessaging_consumer_init(\u0026consumer_name);\n\nconsumer_func should be a function with the following signature\n\n```c\nbool consumer_func(const telemetry_t* packet, message_metadata_t metadata)\n```\n\nTo process packets one should frequently call\n\n```c\nmessaging_consumer_receive(\u0026consumer_name, blocking, silent)\n```\n\nwhere blocking specifies whether to block waiting for packets and silent specifies whether to just drop and not process packets.\n\nAssuming silent is not true and there is a packet waiting a call to messaging_consumer_receive will result in a single call to consumer_func with the packet at the head of the queue.\n\nThe return code of messaging_consumer_receive will indicate if \n- a packet was processed\n- no packet was waiting (will only occur if blocking=false)\n- consumer_func returned false\n\n\n### Component State Component\n\nThe Component State component tracks the 'health' of various software components in the system. Each component can be in one of three states - state_ok, state_initializing and state_error. \n\nThe state of the various components is stored in an array which can be obtained using\n\n```c\ncomponent_state_get_states();\n```\n\nOne can set the state of a component using\n\n```c\nCOMPONENT_STATE_UPDATE(component,state)\n```\n\nThis will automatically obtain the line number of the call to aid debugging.\n\nState updates are sent out using the messaging system, alternatively one can register an error handler function - see [INSTALL.md](INSTALL.md) for more info.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuspaceflight%2Fcusf-messaging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuspaceflight%2Fcusf-messaging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuspaceflight%2Fcusf-messaging/lists"}