CircuitVerse project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
CircuitVerse
Technical writer:
dvls
Project name:
CircuitVerse Interactive Book Consolidation and Improvements
Project length:
Standard length (3 months)

Project description

1 Abstract

CircuitVerse is an open source project aiming to provide a platform where circuits can be designed and simulated using a web-based graphical user interface. The logic simulator can be used to design up to complete CPU implementations, although it is designed primarily for educational use. Besides the technical documentation for the software, an online interactive book guides the user in learning digital logic design. The book allows the user to try out circuits directly from within the book for an interactive experience.

The book is in an early state of development and is currently lacking some relevant sections, the general structure is loose in terms of a flow connecting the different sections, and requires more detailed content. Moreover, according to the organization, there are not guidelines to help contributors to collaborate to the project nor is a plan or road-map to guide contributions on which contents are needed and with which priority.

The aims of this proposal are to collaborate with the mentors to create contribution guidelines, produce a topic development plan and contribute with improving current content as well as create new content according to the development plan.

2 The Current State of the Interactive Book

Since the project's kick-start in Google Summer of Code 2019, it has exhibited an "unmanaged growth", with the help of the student community. The project organization itself is formed mainly by developers, therefore they have taken part of the GSoD to seek for external help to improve the Interactive Book. The project's developers have identifies that the book is currently requiring the rewrite of some sections, new content addition and make it more detailed and comprehensive. Moreover, the team expect to have, after the GSoD, guidelines for new contributions as well as a general "master plan" for the content development.

3 What is the contribution of this proposal

This proposal will contribute with the co-creation of a first version of contribution guidelines, aiming to ensure a more harmonic process of collaboration for contributors, thus leading to more consistent contents. A development plan for the book's topics will also be outlined. The most urgent additions and changes according to the new development plan will also be contributed.

4 Analysis of available alternatives

Several mature open source projects of similar characteristics have already developed contribution guidelines for documentation, such as Wikibooks ([Help:Contributing], [Wikibooks:Policies and guidelines]), OpenStreetMap ([Organised Editing Guidelines]) or The Linux Documentation Project ([LDP Author Guide]). These examples can be used to build the project's guidelines based on the experience of successful open source projects.

For the topic's development plan it is possible to compare syllabi of open courses (e.g. [MIT Open Courseware]) as well as reference books about digital logic circuits, including open books such as [Lessons In Electric Circuits -- Volume IV -Digital], [Wikibooks: Digital Circuits] and [Wikibooks: Digital Electronics].

[Help:Contributing] https://en.wikibooks.org/wiki/Help:Contributing

[Wikibooks:Policies and guidelines] https://en.wikibooks.org/wiki/Wikibooks:Policies_and_guidelines

[Organised Editing Guidelines] https://wiki.osmfoundation.org/wiki/Organised_Editing_Guidelines

[LDP Author Guide] https://www.tldp.org/LDP/LDP-Author-Guide/html/index.html

[MIT Open Courseware] https://ocw.mit.edu/

[Lessons In Electric Circuits -- Volume IV -Digital] https://www.ibiblio.org/kuphaldt/electricCircuits/Digital/index.html

[Wikibooks: Digital Circuits] https://en.wikibooks.org/wiki/Digital_Circuits

[Wikibooks: Digital Electronics] https://en.wikibooks.org/wiki/Digital_Electronics

5 Structure of the proposed documentation

The interactive book has the potential to be useful for a broad audience ranging from amateur electronic hobbyist and secondary education students to tertiary education students and professionals in need of refreshing or strengthening their skills in digital logic circuits.

In order to address the heterogeneity in the book's users a "multi-layer" structure is proposed, where each layer correspond to increasing level of complexity and theoretical depth of the contents.

Therefore, the documentation's structure grows in two dimensions, the first dimension corresponds to the logical or traditional sequence of topics in digital logic systems, while the second dimension represents the level.

In the following structured list the proposed two-dimensional structure is represented. The standard topic sequence is presented in the topmost level. For simplicity, only three layers of complexity are defined for each topic, corresponding to basic, medium and advanced levels. For each level the contents related to the specific general topic are listed.

  • Representation using binarty numbers:
    • Basic level: Binary numbers, Negative quantities, Other bases, Codification.
    • Medium level: [no specific content]
    • Advanced level: Modules and rings
  • Mathematical operations with binary numbers:
    • Basic level: Addition, Subtraction, Multiplication, Division
    • Medium level: Boolean algebra, Boolean functions
    • Advanced level: Other algebras, Shannon decomposition
  • Combinational SSI components:
    • Basic level: Symbols, Logic gates, Truth tables
    • Medium level: Logic families, Universal gates
    • Advanced level: Time behaviour (timing models, hazards)
  • Combinational logic design:
    • Basic level: Functional description, Implementation
    • Medium level: Canonical functions, k-Maps
    • Advanced level: Map-entered variables, Quine McCluskey, Binary cubes representation
  • Combinational MSI components:
    • Basic level: MUX, DEMUX, Encoder, Decoder, Half adder, Full adder
    • Medium level: MUX based functions
    • Advanced level: [no specific content]
  • Combinational LSI components:
    • Basic level: ROM, ALU
    • Medium level: PLDs (PLA, PAL, GAL)
    • Advanced level: [no specific content]
  • Sequential SSI components:
    • Basic level: Latches, Flip-flops, Clock signals, Time diagrams
    • Medium level: Memory Feedback, Synchronous systems, Asynchronous systems
    • Advanced level: [no specific content]
  • Sequential MSI components:
    • Basic level: Registers, Counters
    • Medium level: [no specific content]
    • Advanced level: [no specific content]

  • Sequential design:

    • Basic level: [no specific content]
    • Medium level: Sequential synthesis, FSM (Mealy, Moore), State diagrams, State minimization, State assignment, Race conditions
    • Advanced level: MSI based design, LSI based design, Flow diagrams, MDS diagrams

    The basic level should allow users to understand how digital logic circuits work and how to use them, without requiring knowledge of higher maths. Thus, it could be suitable for amateur hobbyist and secondary education students. If these users have the necessary skills and want to build a deeper understanding, they can work some or all the contents of the medium level.

    The medium level should be equivalent in contents and requirements to a tertiary education level introductory course in digital logic system.

    Finally, the advanced level includes contents which can usually be found in complementary or optional advanced courses of digital systems in universities.

    This proposed structure will be discussed with the mentors in the early phase of the project (Week 3), which will then be used as an input to outline a long-term topic development plan.

    The proposed structure can make use of most, if not all, the current content of the documentation, which will be revised and extended or corrected accordingly, when necessary. Moreover, new sections will be written for those contents which are not yet covered by the existing documentation.

6 Goals

  1. Produce a first draft of contribution guidelines for the Interactive Book project.
  2. Outline a development for the book's topics.
  3. Rewrite and restructure current content.
  4. Create new content according to the development plan.

7 Timeline

Week 1: (Sep. 14th - Sep. 20th) Analyse and discuss with the mentors the best guidelines based on other project's examples as well as the experience obtained so far in the project. Week 2: (Sep. 21st - Sep. 27th) Write the draft of the guidelines Week 3: (Sep. 28th - Oct. 4th) Discuss draft of topic development plan with mentors. Week 4: (Oct. 5th - Oct. 11th) Write development plan. Weeks 5 to 11: (Oct. 12th - Nov. 29th) Write the contributions, consisting in restructured content as well as new topics. Week 12: (Nov. 30th - Dec. 5th) Project report submission. Project evaluation: (Dec. 3rd - Dec. 10th) - Technical writer's evaluation submission. - Mentors' evaluation submission.

8 Why the CircuitVerse Interactive Book

Due to the COVID-19 global crisis, I started looking for on-line resources which would help my students of a undergraduate course on digital logic systems. I have been an advocate of Free-Libre Open Source technologies for several decades now, so I give priority to these kind of projects. I found the CircuitVerse simulator and I decided it was a great tool to supplement the lack of laboratory activities due to the COVID-19 containment measures of our University. While testing the simulator, I also found their Interactive Book, and even though the content was not yet enough as the main reference for a complete course on digital logic systems its current contents were correct and easy to understand so I included it to the learning resources.

Since I was using their simulator and book intensively I was contacted by the organization to tell me about the GSoD. I saw in this an opportunity to contribute back to the project straight from my area of expertise.

9 References

  • [Wikibooks Help:Contributing],
  • [Wikibooks:Policies and guidelines]
  • [OpenStreetMap Organised Editing Guidelines]
  • [The Linux Documentation Project (LDP) Author Guide]
  • [MIT Open Courseware Introductory Digital Systems Laboratory Syllabus]
  • [Lessons In Electric Circuits -- Volume IV -Digital]
  • [Wikibooks: Digital Circuits]
  • [Wikibooks: Digital Electronics]

  • [The Linux Brochure Project]

    [Wikibooks Help:Contributing] https://en.wikibooks.org/wiki/Help:Contributing

    [Wikibooks:Policies and guidelines] https://en.wikibooks.org/wiki/Wikibooks:Policies_and_guidelines

    [OpenStreetMap Organised Editing Guidelines] https://wiki.osmfoundation.org/wiki/Organised_Editing_Guidelines

    [The Linux Documentation Project (LDP) Author Guide] https://www.tldp.org/LDP/LDP-Author-Guide/html/index.html

    [MIT Open Courseware Introductory Digital Systems Laboratory Syllabus] https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-111-introductory-digital-systems-laboratory-spring-2006/syllabus/

    [Lessons In Electric Circuits -- Volume IV -Digital] https://www.ibiblio.org/kuphaldt/electricCircuits/Digital/index.html

    [Wikibooks: Digital Circuits] https://en.wikibooks.org/wiki/Digital_Circuits

    [Wikibooks: Digital Electronics] https://en.wikibooks.org/wiki/Digital_Electronics

    [The Linux Brochure Project] http://lbproject.sourceforge.net/