{"id":22038310,"url":"https://github.com/opencyphal/specification","last_synced_at":"2025-05-07T21:25:15.955Z","repository":{"id":40476574,"uuid":"139164496","full_name":"OpenCyphal/specification","owner":"OpenCyphal","description":"The Cyphal specification documents are maintained here.","archived":false,"fork":false,"pushed_at":"2025-03-14T10:22:00.000Z","size":4634,"stargazers_count":43,"open_issues_count":12,"forks_count":13,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-05-07T03:30:34.788Z","etag":null,"topics":["aerospace","can-bus","canbus","communication-protocol","cyphal","drone","drones","latex","open-standard","opencyphal","robotics","uavcan","unmanned-aerial-vehicle"],"latest_commit_sha":null,"homepage":"https://opencyphal.org/specification","language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenCyphal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null},"funding":{"open_collective":"opencyphal","github":"OpenCyphal"}},"created_at":"2018-06-29T15:15:39.000Z","updated_at":"2025-03-29T14:38:18.000Z","dependencies_parsed_at":"2024-01-20T01:01:34.141Z","dependency_job_id":"a113999a-47a5-4efd-9286-8938e17b1443","html_url":"https://github.com/OpenCyphal/specification","commit_stats":{"total_commits":566,"total_committers":12,"mean_commits":"47.166666666666664","dds":"0.14310954063604242","last_synced_commit":"89b9ff6e2a5a417b53bf462b497586e82c28b5ec"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCyphal%2Fspecification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCyphal%2Fspecification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCyphal%2Fspecification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCyphal%2Fspecification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenCyphal","download_url":"https://codeload.github.com/OpenCyphal/specification/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252955924,"owners_count":21831202,"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":["aerospace","can-bus","canbus","communication-protocol","cyphal","drone","drones","latex","open-standard","opencyphal","robotics","uavcan","unmanned-aerial-vehicle"],"created_at":"2024-11-30T11:05:28.048Z","updated_at":"2025-05-07T21:25:15.913Z","avatar_url":"https://github.com/OpenCyphal.png","language":"TeX","funding_links":["https://opencollective.com/opencyphal","https://github.com/sponsors/OpenCyphal"],"categories":[],"sub_categories":[],"readme":"# Cyphal specification\n\n[![CI](https://github.com/OpenCyphal/specification/actions/workflows/build.yml/badge.svg)](https://github.com/OpenCyphal/specification/actions)\n[![Forum](https://img.shields.io/discourse/https/forum.opencyphal.org/users.svg)](https://forum.opencyphal.org)\n\nThe sources of the Cyphal specification and other related documents are contained here.\n\nWhen cloning this repository, don't forget to initialize the Git submodules:\n`git submodule update --init --recursive`.\n\n## Governance\n\nThe Cyphal specification is community-managed and completely open. Anyone can propose changes but only Cyphal maintainers may commit changes to this repository where the contents of the HEAD revision of the primary branch constitutes the latest version of the specification in-effect.\n\n### Request For Comments (RFC) Process\n\nChanges to the specification shall use the following, community-driven RFC process:\n\n1. An RFC is posted on the [OpenCyphal forum's specification section](https://forum.opencyphal.org/c/dev/spec/15) with the details of the proposed change. The title of this post should start with \"RFC: \" to indicate it is the start of a proposed change to the specification.\n2. RFCs will remain on the forum for at least 10 days to ensure interested parties have time to discover and review them.\n3. After some discussion and review by the community, the RFC is either accepted or rejected by at least one OpenCyphal maintainer.\n4. Once accepted the RFC is implemented in the specification as a pull-request and is considered adopted once the PR has been merged.\n\n## Editing guide\n\n### Style\n\nFollow the Zubax LaTeX guide: \u003chttps://kb.zubax.com/x/IYEh\u003e.\n**Do not edit the document without the spell checker.**\n\nWrite in American English.\n\nCritical definitions (behaviors, constraints, assumptions, etc.) shall be written in the main body of the document.\nOptional content (clarifications, examples, elaborations) is placed either into footnotes or into blue remark boxes\nwhich can be defined using `\\begin{remark}...\\end{remark}`.\n\nNever address the reader directly.\nDo not hesitate to use passive voice.\nFor example, instead of \"you can find the data type X here\", say \"the data type X can be found here\".\n\nFollow [RFC2119](https://tools.ietf.org/rfc/rfc2119.txt).\n\nDo not use title case. Headings and captions are to be written in regular sentence case.\nGenerally, capitalized words can only be used in the beginning of a sentence and in proper names.\n\nDo not put a full stop after a caption unless it contains any other punctuation or is more than one sentence long.\n\nAlways insert a non-breakable space before reference: `refer to section~\\ref{sec:chapter_section}`.\n\nWhen referring to a category of identifiers, put a hyphen before \"ID\"; for example: \"node-ID\" is correct, \"node ID\" is not.\n\nAvoid introduction of new acronyms unless you really must.\nIt is better to say \"transfer-ID\" or \"data type hash\" rather than TID or DTH.\nExcessive reliance on acronyms may impede comprehension.\n\n### Rigging\n\nIn order to refer to a DSDL definition, use macro `\\DSDLReference{}`.\nTo include a DSDL definition or a namespace index, use macro `\\DSDL{}`.\nRefer to the existing usages for an example.\n\n### Structure and cross-referencing\n\nEach chapter is located in a dedicated directory, whose name is a single lowercase word.\nThe main file of the chapter is located in a file under the same name as the directory.\nFor example: `chapter/chapter.tex` (where \"chapter\" is the chapter name placeholder).\n\nWhen defining a new label, you must use the prefix following the pattern `kind:chapter`, where:\n\n- \"kind\" is the kind of the labeled item, such as `fig`, `table`, or `sec`;\n- \"chapter\" is the name of the directory where the chapter is contained.\n\nThe label that contains only the prefix points to the chapter itself using the kind `sec`.\nFor example, if the chapter is named \"Transport layer\", its label would be `sec:transport`.\n\nItems contained inside the chapter (sections, figures, tables) are named using free form\nappended to the prefix.\nFor example, one could refer to a figure contained inside the chapter \"Chapter\" as `fig:chapter_my_figure`.\n\nThe above rules are crucial to follow to keep cross-references usable.\nWithout strict conventions in place, they quickly become unmanageable.\n\n### Source formatting\n\n- One level of nesting shall be indented with 4 spaces. Tabs shall not be used anywhere in the source.\n- There shall be no more than 120 characters per line.\n- There shall be exactly one blank line at the end of the file.\n- There shall be no more than one consecutive blank line.\n- There shall be at most one chapter per source file.\n- There shall be one blank line above and below a section header,\nunless the section header is at the top of the source file.\n- Multi-line content enclosed in curly braces should be indented.\n- If a list item spills on the next line, the spilled text should be indented on the same level with `\\item`.\n\n```tex\n\\begin{itemize}\n    \\item This list item is sufficiently long to exceed the limit of 120 characters per line,\n    so it has to spill onto the next line.\n    The spilled part is indented correctly.\n\n    \\item Another item.\n\\end{itemize}\n\n% The next line contains a comment to remove the whitespace in the beginning of the footnote.\nRegulated non-standard definitions\\footnote{%\n    I.e., public definitions contributed by vendors and other users\n    of the specification, as explained in section~\\ref{sec:basic_data_type_regulation}.\n} are not included in this list.\n```\n\n## Tools\n\n### Compiling\n\nA GNU/Linux-based operating system is assumed.\nThe described instructions may be valid for other operating systems but this is not guaranteed.\n\nIn order to compile the document, install TeX Live\n(Ubuntu packages: [`texlive-full`](https://packages.ubuntu.com/xenial/texlive-full) and `lyx`)\nand the Python packages listed in `requirements.txt`.\n\nWhen done, run `./compile.sh`.\n\n#### Using texer\n\nYou can use our texer container to build the specification if you don't want to setup your own build environment.\nPlease consult with the CI/CD workflow to find out which container version should be used.\nTo enter the container from a local shell, go roughly like this:\n\n```sh\ndocker run -it --rm -v $(pwd):/repo -e LOCAL_USER_ID=`id -u` ghcr.io/opencyphal/texer:te22.4.1 bash\n```\n\n### IDE setup\n\nFirst, ensure that you can compile the document as described above.\nDo not proceed further until that requirement is satisfied.\n\nUse Visual Studio Code with the recommended extensions for editing.\nMore info in the [Zubax Knowledge Base](https://kb.zubax.com/x/IYEh).\n\n#### L33t IDE Setup\n\nIf you want to use our [texer container](https://hub.docker.com/repository/docker/uavcan/texer) with vscode then install the [\"ms-vscode-remote.vscode-remote-extensionpack\"](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) and Docker. When you open vscode in this repository it should prompt you to \"open this folder in container?\". Otherwise `F1` or `CMD+SHIFT+P` and select `Remote-Containers: Reopen Locally`. Once within the container you can simply `F1` or `CMD+SHIFT+P` and `LaTeX Workshop: Build LaTeX project` to build the specification PDF.\n\nThe above [may not work](https://github.com/microsoft/vscode-remote-release/issues/1097) if you are running an OSS build of VSCode (e.g., from Arch AUR). It is recommended to use the official binaries from Micro$oft.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencyphal%2Fspecification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencyphal%2Fspecification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencyphal%2Fspecification/lists"}