search

oceanofthelost / InteractivePCB

interactive PCB viewer
68 stars 15 forks source link

readme

Interactive PCB

SonarCloud

InteractivePCB is a hard fork of InteractiveHtmlBom with a focus interactions with a PCB beyond a bill of materials. To that end, InteractivePCB lets one interaction with individual PCB layers, aid in PCB assembly by showing similar parts, and also provide an interactive BOM.

Currently InteractivePCB is designed to work with EagleCAD with minor support for FusionElectonics and can be displayed using the Chrome web browser.

Table of Contents

  1. About the Project
  2. Project Status
  3. Getting Started
    1. Dependencies
    2. Building
    3. Installation
    4. Usage
      1. EagleCAD
    5. Branch Conventions
  4. Release Process
    1. Creating A Release
      1. Bugfix Release
      2. Feature Release
    2. Versioning
  5. How to Get Help
  6. Contributing
  7. License
  8. Authors
  9. Acknowledgments

About the Project

InteractivePCB started as a hard fork of InteractiveHtmlBom with the goal of adding support for EagleCAD, my choice of electronic CAD software at the time. Later InetractivePCB was used as a platform to learn HTML, JavaScript, CSS, and how to write formal specifications for data format.

InteractivePCB current focus is on integrate additional tools to analyze PCB's and to support additional ElectronicCAD software.

Back to top

Project Status

InteractivePCB is still under active development but developed as time permits to the lead developer with features and enhancements implemented on an as needed basis.

Version 2 is released and can be found under Releases. A Version 3 is in development with plans to release the project in the near future.

Browser support for Interactive PCB is primary for Chrome. Small PCB's may work in Firefox, but an unknown bug Forces Firefox to hand. No testing has been performed on other browsers.

Back to top

Getting Started

The following section outlines how to get started using and developing InteractivePCB. Dependencies, building, and usage shall be covered. For those interested only in using InteractivePCB, you may skip directly to Usage

Dependencies

Following is a list of software expected to be installed:

  1. nodejs
  2. npm
  3. make

Getting the Source

This project is hosted on GitHub and can be cloned by issuing the following command from a terminal:

$ git clone git@github.com:oceanofthelost/InteractivePCB.git

Building

Open a terminal and navigate to GUI folder and issue the following command to build:

$ make

Once issued, make will use npm to install project specific dependencies, then generate InteractivePCB.html and related.

Installation

No installation is necessary, simply have all the following files all in a folder:

  1. index.css
  2. index.js
  3. iPCB.html

Usage

EagleCAD

Start EagleCAD and from a PCB, press ULP button and navigate to ipcb.ulp. Select a folder where to place script output, pcbdata.json. By default project directory is used.

Copy pcbdata.json to a folder created in Installation.

Now open iPCB.html in a web browser.

Back to top

Branch Conventions

Development consists of three primary branches:

  1. master: Primary branch used for commuting all new development. Mastre branch will always consist of the latest software and may contain bugs and is not recommended for everyday use.
  2. Development_V2: Bugfixes and requested minor features to be integrated into V2 are committed to Development_V2 branch. Commits may be cherry picked from master ad added, or fixes may be ported to to master. When V3 is released Development_V2 will be closed and replaced with Development_V3. Primary existence for Developmen_* to provide an area to perform release candidate testing and bug fixes outside of master which may have breaking changes that are not ready for release.
  3. Release: Public releases are merged from master and Development_* branches directly into Release. After enough testing has been preformed on a release candidate it is deemed to be ready for release. All commits on release are tagged with a version number and also correspond to a working implementation of InteractivePCB.

Master branch is used like development branch. Reason master is not named develop is because initial development was by solo developer and solo developer did not care to over complicate development with multiple branches. Now that project has grown this is being addressed and at some point in the future master will be renamed to develop to make it clear where primary development should occur.

Release Process

Creating A Release

Releases fall into one of two categorizes, bugfix and feature. The following section discuss the generic release steps common to both bugfix and feature releases.

Generic steps for creating a release are:

  1. Set new version number in version.js
  2. Open a terminal and navigate to the GUI folder.
  3. Issue make release
  4. Make a new commit on Release by pulling in master.
  5. Tag new release with version number assigned in 1.
  6. Push both Release branch and tags to origin.

The above will generate a zip file iPCB.zip.

Next, from GitHub:

  1. Navigate to releases
  2. Select draft new release
  3. Under Choose a tag select tag corresponding to newest version number
  4. Under release notes, add a changelog of changes between new release and last release.
  5. Add a section on how to download release, unzip and basic steps to use Interactive PCB.
  6. Under "Attach binaries" Upload zip file generated in last step along with any ElectronicCAD plugins.

Bugfix Release

Bugfix releases are designed to address specific issues found in release software. Once an issue is identified and an issue ticket created on GitHub, development will commonsense on fixing the issue. Upon fixing the bug and adding the change to the software, testing will be preformed and when complete will a new release will be made, tagged, and released on [GitHub](released.

Feature Release

Feature releases used for adding new capabilities to InteractivePCB. First a feature request is made by creating a GitHuib issue. Next development on the feature will commence on a new branch and once complete will be merged back into master. When enough features are integrated or a milestone has been reached, then a release candidate will be created. Once a release candidate is made testing will commence to discover and fix any bugs. Once testing is complete a release will be made from the release candidate, tagged, and released on [GitHub](released.

Versioning

InteractivePCB uses Subjective Versioning which is inspired by Semantic Versioning. Subjective Versioning uses MAJOR.MINOR.PATCH-RC# with V prefixed. The following rules are used for incrementing MAJOR, MINOR, and PATCH:

  1. MAJOR increment on breaking changes or at lead developers sole discretion. Upon incrementing MAJOR, MINOR and PATCH will be reset to 0.
  2. MINOR increments on addition of new features not introducing breaking changes or large changes adding no new features or breaking changes. Incrementing minor will reset to zero PATCH.
  3. PATCHincrements for bug fixes and small changes introducing no new features.
  4. RC# is optional and is used for release candidates. For every fix # will increment.

How to Get Help

Two methods exist for getting help related to InetractivePCB.

First and preferred way to request help is to post a questions on the discussion board. If unable to ask a question on the discussion forum, you may also file an issue and adding the label help to the ticket.

In both cases of communication, do not worry, your request will be reviewed but a response may not or answered right away. Answer by the lead developer are made as time permits.

Contributing

We encourage public contributions! Please review CONTRIBUTING.md for details on our development process and our code of conduct before you do!

Back to top

License

??????????????

Back to top

Authors

Also see the list of contributors who participated in this project.

Back to top

Acknowledgments

Thank you to the following for inspiration and assistance on this project.

Embedded Artistry for the thorough README template.

Code Thessaurus for our code of conduct and issue and PR templates.

openscopeproject for providing InteractiveHtmlBom for without, this project would not exist.

Back to top