diff --git a/docs/content/docs/Principle Philosophies/cujs.md b/docs/content/docs/Principle Philosophies/cujs.md index abdf576..2a3fa72 100644 --- a/docs/content/docs/Principle Philosophies/cujs.md +++ b/docs/content/docs/Principle Philosophies/cujs.md @@ -7,15 +7,27 @@ description: > --- Defining Critical User Journeys (CUJs) will allow the development of this project -to align with goals and expectations of the project consumers. +to align with goals and expectations of the project consumers so that we can rank them in our roadmap. -## Preventing typos -I am an engineer who wants to connect a pressure sensor to a microcontroller. When I tried to -build a peripheral driver for the sensor and read the value, it read 9 hPa. For reference, -the average pressure on Earth is ~1000 hPa. The reason was that I made a typo in copying from -the datasheet, performing multiplication instead of divison. This simple error could be mitigated -by having a standardized specification that requires no explicit work to get the library in the -platform of my choice. +If you have a new use case that is not included in this document, feel free to add it. + +While this feels perhaps a bit unorthodox for an open source project, it is important that we take into +consideration the many different users of the specification to allow for broad adoption. + +## Embedded Software Engineer +It is expected that the primary users of the project are embedded developers. +The CyanoByte specification creates a standardized format for datasheets so that the +developer does not have to switch between many different formats. Additionally, it allows +for code stubs to be created to more quickly develop firmware that uses a particular chip. + +Additionally, simple errors could be mitigated by having a standardized specification that +requires no explicit work to get the library in the platform of choice. + +**Key Competitive Advantages:** + +* Reduce the development time by automatically generating the non-application specific logic +* Make reading datasheets more efficient by creating a standardized format and interface +* More rapidly create proof-of-concepts using higher-level languages such as Python that can then be easily ported to embedded platforms ## Sensor Hardware Manufacturer I am a customer support engineer at a sensor chip manufacturer. In the past my role has been to assist @@ -28,6 +40,26 @@ I decided to create a Cyanobyte specification file for one of our chips and made download on our store's website. The number of support queries has been reduced, and customers are now more pleased. This seems to have led to an increase in customer satisfaction and retention. +In order for the standard to become universally used, it is critical to get buy-in from manufacturers of +electronic components. The CyanoByte specification can be used as both an internal tool during the +development of a new peripheral that is formally defined and unambiguous as well as an external tool +for developing datasheets and users guides. Additionally, by automatically generating example code in +multiple programming languages for multiple platforms, the cost to create examples is greatly reduced. + +**Key Competitive Advantages:** + +* Reduce development time of code examples + +## Electronics Distributors +The CyanoByte specifications provide a new source of information that can be used for novel +parametric search tools. + +**Examples:** + +* DigiKey (https://www.digikey.com/) +* Arrow (https://www.arrow.com/) +* Mouser (https://www.mouser.com/) + ## Oceanography I am a researcher in Florida who is developing and deploying remotely operated vehicles (ROVs) in the state's waterways to observe local wildlife and collect data related to water quality. This @@ -79,13 +111,19 @@ refocus on building and marketing new products ## New IoT Platform I am the product manager of a new IoT platform. We launched our first product several months ago but have not been seeing a lot of traction. A big piece of criticism is a lack of software support. Our -platform doesn't have many drivers for common peripherals, which prevents a lot of adoption, which prevents a growing community from writing drivers. +platform doesn't have many drivers for common peripherals, which prevents a lot of adoption, which +prevents a growing community from writing drivers. To resolve the chicken & egg problem, we build and release a Cyanobyte template file for our platform. Suddenly, we are able to support a growing set of sensors and other peripherals without having to take on the maintenance burden. As our platform may have some unusual idiosyncracies, providing an off-the-shelf template file allows for high-quality drivers and code to be generated. +The CyanoByte generators may be used by, created by, or maintained by microcontroller manufacturers. +If enough peripherals are available, then maintaining a CyanoByte generator for a particular +microcontroller given the manufacturer a competitive advantage as it makes development on their +platform far quicker and easier than others. + ## Student Project I am a student at a school that specializes in engineering. My background is primarily in computer engineering, although I have some experience in the C programming language. I am working on an embedded @@ -96,4 +134,26 @@ I do an online search and find a Cyanobyte specification file for the peripheral source project which is a Cyanobyte template file for the microcontroller I'm using. After setting up the codegen tool and generating a driver, I import it into my project and it now works -in just a few minutes. Now I have time to write the accompanying report. \ No newline at end of file +in just a few minutes. Now I have time to write the accompanying report. + +## Electronics Hobbyist + +The electronics hobbyist market may be a key early user of the specification while it is under development. + +## Data Scientists and Machine Learning Engineers + +The CyanoByte specifications provide a new source of data that was not previously accessible before. + +## Electronic Computer Aided Design Tools (ECAD) + +Creators of ECAD tools can use the CyanoByte specifications to provide better hardware definitions. At +the moment, the electronic part values are not defined, but this could be a good extension to consider +in the future. + +## Other Related Standards + +The scope of CyanoByte is intentionally limited to only embedded communications at the logical level. +It does not take into account anything related to the electrical signals. + +Therefore it is expected that the CyanoByte standard should work in conjunction with other standards +that may already or eventually exist. \ No newline at end of file diff --git a/docs/content/docs/Principle Philosophies/philosophy.md b/docs/content/docs/Principle Philosophies/philosophy.md new file mode 100644 index 0000000..130a625 --- /dev/null +++ b/docs/content/docs/Principle Philosophies/philosophy.md @@ -0,0 +1,54 @@ +--- +title: "Philosophy and Goals" +linkTitle: "Philosophy and Goals" +weight: 4 +description: > + Philosophy and goals? +--- + +# Philosophy and goals of CyanoByte + +CyanoByte is a project whose goal is to create a standardized specification for representing +hardware peripheral characteristics and functions in a static configuration. This could be +likened to a machine-readable representation of a datasheet. + +Like a datasheet, this intermediate representation (IR) should not just contain a table of registers +and values, but also functionality. This includes a series of steps that represent common +actions like initializing, closing, and other common use-cases. Temperature sensors, for example, +may need to be converted from a raw value to Celsius. This step should be represented in the +IR. + +Everything should be defined so that the client can use this IR as a fully-functioning library. +Anything that a well-developed client library would do, should be automatically generated. Any +device-specific logic should be represented in the IR. + +Platform-specific logic, such as the code to perform hardware connectivity, should be defined in +a platform template (PT) in a flexible way. The IR should be processed and laid into the PT. + +A core goal is minimizing the integration time of hardware peripherals into a specific hardware +platform. As such, one needs to go beyond a simple set of registers and handle flows. Further +efforts to minimize integration time through a static configuration would also be useful to +explore through the development of this project. + +At the moment, the project will only cover I2C. Many I2C devices use SMBus as a common format to +communicate and have straightforward data representation. + +Throughout this exercise, common principles should be extracted to guide future decision +making the project. + +## Goals +- The spec should be representative of how things are currently done, even if it is less "proper" or correct. +- The spec should provide everything needed to generate and publish a client library, with one-line import and one-line init +- The spec should should contain a way to provide a series of logical steps for computation +- The spec should be flexible enough to represent any hardware peripheral +- The spec should be easily human-readable, so that hardware engineers do not need to learn a complex format + +## Anti-goals +- The spec should not have dependencies on a specific programming language or reference specific implementations + - An I2C device yaml representation should not have a preference on which I2C library is used on the Raspberry Pi +- The spec should not be concerned about backwards compatibility + - This will change in the future, but during a prototyping phase we should not be concerned about this +- The pseudo-yaml spec should not allow for flexible code functions such as importing libraries + - Libraries then require a package manager, and a public host, and that's major scope creep +- The pseudo-yaml spec should not be developed into a full programming language + - This could result in versioning problems and template incompatibilities \ No newline at end of file diff --git a/docs/content/docs/Reference/quirks.md b/docs/content/docs/Reference/quirks.md new file mode 100644 index 0000000..8ebb8b2 --- /dev/null +++ b/docs/content/docs/Reference/quirks.md @@ -0,0 +1,12 @@ +--- +title: "Strange chip quirks" +linkTitle: "Strange chip quriks" +weight: 4 +description: > + This is a directory of strange peripheral chip quarks that were unexpected or unintuative. +--- + +## BMP280 + +* Multiple register values can have the same logical interpretation. For the register settings osrs_t[2:0] the following values all mean that the setting is oversampling x16: 0b101, 0b110, and 0b111. This means that they can't be represented as a typical enum in the generated code. It should likely always write one of the values and read all values with the correct interpretation. +* There is an I2C command to enable the SPI interface. \ No newline at end of file diff --git a/docs/content/docs/Reference/unanswered.md b/docs/content/docs/Reference/unanswered.md new file mode 100644 index 0000000..ac4b3b6 --- /dev/null +++ b/docs/content/docs/Reference/unanswered.md @@ -0,0 +1,7 @@ +--- +title: "Unanswered questions" +linkTitle: "Unanswered questions" +weight: 4 +description: > + Some peripherals have default values they are set to on reset. Should we include that information in the specification? +--- \ No newline at end of file diff --git a/docs/content/docs/_index.md b/docs/content/docs/_index.md index 68501d9..c3bc762 100644 --- a/docs/content/docs/_index.md +++ b/docs/content/docs/_index.md @@ -5,4 +5,8 @@ weight: 20 menu: main: weight: 20 ---- \ No newline at end of file +--- + +CyanoByte is a YAML based specification for formally defining embedded communications. +It allows for both documentation and code to be generated from the CyanoByte files. +The specification was greatly inspired by the successes of OpenAPI. \ No newline at end of file diff --git a/docs/cyanobyte.md b/docs/cyanobyte.md deleted file mode 100644 index ba09ca0..0000000 --- a/docs/cyanobyte.md +++ /dev/null @@ -1,126 +0,0 @@ -# CyanoByte Specification - -This file contains a proposed updated CyanoByte specification. It is currently a work in progress and aimed at spurring a discussion surrounding what the specification should look like. - -The CyanoByte specification is a tool to describe the interface to embedded communications in a machine-readable format. It builds off the successes of OpenAPI for web APIs. - -## Philosophy of CyanoByte - -Throughout this exercise, common principles should be extracted to guide future decision making the project. - -- The spec should be representative of how things are currently done, even if it is less "proper" or correct. - -## Roadmap and Items to Consider -- I2C - - How do we deal with addresses that are configurable? - - How do we support sequential register reads for certain chips? -- SPI -- UART - - How do we support the common methods for encoding data sent over UART? Do we make the specification extendable with custom extensions and plugins in the codegen? -- USB - - Do we want to even attempt this? - -## Example Specification - -An example specification for part of the [MCP9808 chip](http://ww1.microchip.com/downloads/en/DeviceDoc/25095A.pdf). - -NOTE: This is designed as an example to uncover the spirit of the documentation and not to be perfectly accurate. - -```yaml -cyanobyte: 0.1.0 -info: - title: MCP9808 - package: com.cyanobyte - description: This is a test description - contact: - name: 'Joe Smith' - url: 'example.com' - email: 'joe@example.com' - license: - name: 'Apache 2.0' - url: 'https://www.apache.org/licenses/LICENSE-2.0.html' - version: 0.1.0 -i2c: - addressType: '7-bit' # Could be '7-bit', '8-bit', or '10-bit' - address: 0x18 - addressMask: 0x78 # This specifys which address bits are configurable - endian: 'big' # Could be 'little' or 'big' endian - -registers: - - configuration: - address: 0x01 - length: 16 - title: Configuration Register - description: The MCP9808 has a 16-bit Configuration register (CONFIG) that allows the user to set various functions for a robust temperature monitoring system. Bits 10 through 0 are used to select the temperature alert output hysteresis, device shutdown or Low-Power mode, temperature boundary and critical temperature lock, and temperature Alert output enable/disable. In addition, Alert output condition (output set for TUPPER and TLOWER temperature boundary or TCRIT only), Alert output status and Alert output polarity and mode (Comparator Output or Interrupt Output mode) are user-configurable - -functions: // Should this be called functions or values or what? - - limitHysteresis: - title: TUPPER and TLOWER Limit Hysteresis bits - description: | - This bit can not be altered when either of the Lock bits are set (bit 6 and bit 7). - This bit can be programmed in Shutdown mode. - register: '#/registers/configuration' # What should the syntax be when it is split among multiple registers? - readWrite: 'R' # Could be 'R', 'W', or 'R/W' - bitStart: 10 - bitEnd: 9 - type: 'enum' - enum: - - 0C: - title: 0°C (power-up default) - value: 0b00 - - 1C5: - title: +1.5°C - value: 0b01 - - 3C: - title: +3.0°C - value: 0b10 - - 6C: - title: +6.0°C - value: 0b11 - - shutdownMode: - title: Shutdown Mode bit - description: | - In shutdown, all power-consuming activities are disabled, though all registers can be written to or read. - This bit cannot be set to ‘1’ when either of the Lock bits is set (bit 6 and bit 7). However, it can be cleared to ‘0’ for continuous conversion while locked. - register: '#/registers/configuration' - readWrite: 'R' - bitStart: 8 - bitEnd: 8 - type: 'enum' - enum: - - continousConversion: - title: Continuous conversion (power-up default) - value: 0 - - shutdown: - title: Shutdown (Low-Power mode) - value: 1 - - critLock: - title: TCRIT Lock bit - description: | - When enabled, this bit remains set to ‘1’ or locked until cleared by an internal Reset. - register: '#/registers/configuration' - bitStart: 7 - bitEnd: 7 - type: 'enum' - enum: - - unlocked: - title: Unlocked. TCRIT register can be written (power-up default) - value: 0 - - locked: - title: Locked. TCRIT register can not be written - value: 1 - - tempBoundary: - title: Temperature Boundary bits - type: 'twos-complement' - computed: - - asTemp: // https://en.wikipedia.org/wiki/Pseudocode aka pseudo-yaml - input: test // Not here, but somewhere - variables: - - temp: float32 - logic: - - if: value > 256 - - temp:= value - - else: - - temp:= 0 - return: temp -``` \ No newline at end of file diff --git a/docs/psuedoyaml.md b/docs/psuedoyaml.md deleted file mode 100644 index afcf51f..0000000 --- a/docs/psuedoyaml.md +++ /dev/null @@ -1,182 +0,0 @@ -# PseudoYAML Spec - -PseudoYAML is a sub-specification of CyanoByte that allows for code to be specified in a method that can be easily translated into multiple different languages. PseudoYAML is not designed to be able to be run independently and is intentionally restricted to only programming concepts standard to all languages. - -## Philosophy of PseudoYAML - -- Everything is strongly typed as it is easier to ignore the type than infer it. -- Limit control flow and looping etc to minimal necessary. PseudoYAML is not intended to be used for complicated logic. -- Support the vast majority of variable types -- The intent of PseudoYAML is to easily create computed and helper values. It is not intended to be used for complex application specific logic. Therefore, we intentionally only support a very limited subset of use cases. If this does not work for your application, then you must work at a higher level. - -## Language Features and Syntax -### PseudoYAML Block - -A block of PseudoYAML contains only three keys: `input`, `variables`, and `logic`. No other keys should be included in a Pseudo-YAML block, however they may be omitted if they would otherwise be empty. - -The `input` block contains a list of all input variables to the PseudoYAML block. Each element in the input block should contain the type as specific in section X. The `variables` block contains a list of all temporary variables and output variables used within the script / logic. - -The `logic` block contains the actual logic of the script. As defined in sections X - X, the `logic` block can contain control flow statements, loops, and other common software features. - -An example of a PseudoYAML block is listed below: - -```yaml -triangleAreaMinSize: - input: - - base: float32 - - height: float32 - variables: - - area: float32 - logic: - - if: area <= 5: - - return: 0 - - else: - - return: area -``` - -### Control Structures - -#### If / Else Statements - -```yaml -exampleIfStatement: - input: - - x: int32 - logic: - - if: x > 2 - - return: x - - else: - - return: 0 -``` - -#### Else If Statements - -```yaml -exampleElseIfStatement: - input: - - x: int32 - logic: - - if: x == 0 - - return: 0 - - else if: x == 1 - - return: 1 - - else if: x == 2 - - return: 1 - - else: - return: -1 -``` - -#### For Loops - -```yaml -exampleForLoop: - input: - - x: int32 - variables: - - i: int32 - - acc: int32 - logic: - - i:= 0 - - for: - - condition: i < 10 - - increment: i - - do: - - acc := acc + 1 - - return: acc -``` - -#### While Loops - -```yaml -exampleWhileLoop: - input: - - x: int32 - variables: - - i: int32 - - acc: int32 - logic: - - i:= 0 - - while: i < 10 - - acc := acc + i - - i := 1 - - return: acc -``` - -#### Assignment - -```yaml -exampleAssignment: - input: - - x: int32 - variables: - - y: int32 - logic: - - y := x - - return: y -``` - -#### Types - -```yaml -exampleTypes: - variables: - - testInt8: int8 - - testInt16: int16 - - testInt32: int32 - - testInt64: int64 - - testUint8: uint8 - - testUint16: uint16 - - testUint32: uint32 - - testUint64: uint64 - - testFloat16: float16 - - testFloat32: float32 - - testBool: bool - - testChar: char - - testString: str - - testEnum: enum - - option1 - - option2 - - testArray: - - type: int16 - - length: 10 - logic: - - return: testInt8 -``` - -#### Type Conversion - -```yaml -exampleTypeConversion: - input: - - x: int32 - variables: - - y: float16 - logic: - - y := (float16) x - - return: y -``` - -#### Operators - -```yaml -- y := x && z // Logical AND -- y := !x // Logical NOT -- y := x || z // Logical OR -- y := x & z // Bitwise AND -- y := ~x // Bitwise NOT -- y := x | z // Bitwise OR -- y := x + z // Addition -- y := x - z // Subtraction -- y := x / z // Division -- y := x * z // Multiplication -- y := x ** z // Exponential -- y := x << z // Bit shift left -- y := x >> z // Bit shift right -- y := x % z // Modulous -- y := x < z // Less than -- y := x <= z // Less than or equal to -- y := x > z // Greater than -- y := x >= z // Greater than or equal to -- y := x == z // Equality -- y := x != z // Not equal to -``` \ No newline at end of file