README.md

@@ -1,3 +1,99 @@
-# Action-carbon-emission-calculator-Demo
+# Carbon Emission Calculator AllSpice Actions Demo
+This is repository with an Altium-based design for demonstrating the "Carbon Emission Calculator" AllSpice Actions add-on.
 
-A repository for demonstrating the "Carbon Emission Calculator" AllSpice Actions add-on.
+This action uses the [generate-bom](https://hub.allspice.io/Actions/generate-bom) and [carbon-emission-calculator](https://hub.allspice.io/Actions/carbon-emission-calculator) Actions add-ons publically available in the [AllSpice Hub Actions](https://hub.allspice.io/Actions) organization.
+
+As shown and explained below in the YML workflow file, the generate-bom add-on is used to generate a BOM using the py-allspice BOM generation utility function, and the carbon-emission-calculator add-on is used to obtain mock carbon emission data for the Archimajor 3D printer BOM components from a repository-based data source.
+
+## Usage
+
+### Step 1) Modify emission data ingestion in the add-on to your need:
+
+The carbon-emission-calculator add-on uses a standalone data source CSV file with mock emissions figures for each component in the Archimajor 3D printer PCBA BOM. For your specific use, you will need to provide a data source and modify the data ingestion or query from source to match your needs:
+
+#### For CSV-based data sources:
+
+Replace your data source URL with the mock data URL in the add-on. The file format assumes part number as the 1st column, and the emission figure as the second column:
+```
+ALLSPICE_DEMO_CARBON_EMISSION_DATA_URL = "https://hub.allspice.io/AllSpice-Demos/Demo-Data-Source/raw/branch/main/Carbon-Emissions-Figures-Archimajor/archimajor-carbon-emissions-figures.csv"
+```
+
+#### For Database-based data sources:
+
+If your emissions data is stored in a database, you will need a service to present that data via a queryable API endpoint. A rudimentary example of querying an API endpoint for emissions data is shown below:
+
+```
+ALLSPICE_DEMO_CARBON_EMISSION_DATA_API_URL_BASE = "https://your.site"
+ALLSPICE_DEMO_CARBON_EMISSION_DATA_PART_SEARCH_ENDPOINT = ALLSPICE_DEMO_CARBON_EMISSION_DATA_API_URL_BASE + "/get_emission_figure/"
+
+################################################################################
+def query_demo_carbon_emission_data_for_mfr_part_number(url):
+    # Post the request and get the response
+    response = requests.get(url)
+    # Populate the search result return value
+    part_search_response = response.text
+    # Return response status code and search result
+    return (response.status_code, part_search_response)
+```
+
+### Step 2) Add the following step to your actions:
+
+```yaml
+# AllSpice running carbon emission calculator demo workflow
+# Action triggers on push and issues
+# Action runs "carbon-emission-calculator" action
+# .allspice/workflows/Carbon-Emission-Calculator.yml
+name: Generate Carbon Emission Figure for PCBA
+on:
+  push:
+  issues:
+    types: [opened, closed, reopened]
+
+jobs:
+  Generate_PCBA_Carbon_Emission_Figure:
+    runs-on: ubuntu-latest
+    steps:
+      # Checkout is only needed if columns.json is committed in your Altium project repo.
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Generate BOM
+        uses: https://hub.allspice.io/Actions/generate-bom@v0.3
+        with:
+          # The path to the project file in your repo (.PrjPcb for Altium, .DSN for OrCad).
+          source_path: Archimajor.PrjPcb
+          # [optional] A path to a JSON file mapping columns to the component attributes
+          # they are from. This file must be provided.
+          # Default: 'columns.json'
+          columns: .allspice/columns.json
+          # [optional] The path to the output file that will be generated.
+          # Default: 'bom.csv'
+          output_file_name: bom.csv
+          # [optional] A comma-separated list of columns to group the BOM by. If empty
+          # or not present, the BOM will be flat.
+          # Default: ''
+          group_by: "Part Number"
+          # [optional] The variant of the project to generate the BOM for. If empty
+          # or not present, the BOM will be generated for the default variant.
+          # Default: ''
+          variant: ""
+
+      # Print bom.csv to terminal
+      - name: Show BOM
+        run: cat bom.csv
+
+      # Upload BOM as artifact
+      - name: Upload file as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: BOM.csv
+          path: bom.csv
+
+      - name: Generate Carbon Emission Figure for PCBA
+        uses: https://hub.allspice.io/Actions/carbon-emission-calculator.git@v1
+        with:
+          # The input BOM file for carbon emissions calculator
+          bom_file: bom.csv
+```
+
+Refer to the [generate-bom](https://hub.allspice.io/Actions/generate-bom) and [carbon-emission-calculator](https://hub.allspice.io/Actions/carbon-emission-calculator) add-on pages for usage and background on the add-ons used in this workflow demonstration.