From bfbb7d10a6d0a26db3ee4c35411fcc195be7767f Mon Sep 17 00:00:00 2001 From: Gautam Peri Date: Tue, 23 Jul 2024 14:39:15 -0500 Subject: [PATCH] Updating README with usage information --- README.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 98 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a07c471..d808457 100644 --- a/README.md +++ b/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. -- 2.40.3