Documentation merges

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.
+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.

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

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.

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?
+---

docs/content/docs/_index.md

@@ -5,4 +5,8 @@ weight: 20
 menu:
   main:
     weight: 20
----
+---
+
+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.