Scripts

Actions Scripting

AllSpice Actions can run any scripting or programming language that runs on the latest Ubuntu Long-Term-Service (LTS).

Bash scripts

Bash scripts are the simplest thing to run in a Task. You can leverage the power of the Linux CLI to process data, make simple API calls, and call other programs. Python has many advantages over Bash scripts, but many workflows use a combination of the two.

Python scripts

Python is the preferred programming language for Electrical Engineers, for it’s ease of use and extensive module library.

Our documentation predominantly features Python based on it’s popularity, ease of use, robustness, and performance. There are countless Python modules such as PANDAS or JSON that help with data processing.

Our our py-allspice Python wrapper allows you to quickly and easily access your repository files, issues, design reviews, and releases.

Here is an example Python script using py-allspice

from allspice import *

# By default, points to hub.allspice.io.
allspice_client = AllSpice(token_text=TOKEN)

# If you are self-hosting:
allspice_client = AllSpice(allspice_hub_url=URL, token_text=TOKEN)

Here is our py-allspice documentation, making it easy to quickly find the call or module you need to interact with AllSpice.

You can check out our API documentation if you want to write your own HTTP requests.

Passing variables to scripts

The provided Python code snippet illustrates how to initialize an AllSpice client to interact with the AllSpice Hub API using the allspice library. By default, when you create an -instance of the AllSpice class with only the token_text parameter, it connects to the public AllSpice Hub at hub.allspice.io. This is suitable if you’re using the cloud-hosted version of AllSpice. However, if you’re running a dedicated-hosted instance of AllSpice Hub, you need to specify the allspice_hub_url parameter with the URL of your server. In both cases, the token_text parameter is required for authentication, allowing the client to securely communicate with the AllSpice Hub API, whether it’s the default hosted service or your own self-hosted instance.

The workflow file needs to pass AllSpice Authentication details to the python script.

# Python-py-allspice demo repository
# This workflow demonstrates how to use Python and py-allspice to interact with the AllSpice API
# AllSpice Actions documentation: https://learn.allspice.io/docs/actions-cicd
name: Python-py-allspice
on: 
  push:
  issues:
    types: [opened, closed, reopened]

jobs:
  py-allspice test:
    runs-on: ubuntu-latest
    steps:
      # Check out repository code
      - name: "[📚->🖥️] Check out repository code"
        uses: actions/checkout@v4

      - name: "[🔎->📂] List files in repo 🔎"
        run: |
          ls -la ${{ allspice.workspace }}          

      # Installs python requirements from the requirements.txt file
      - name: "[🤼->🖥️] Install python requirements"
        run: pip install -r .allspice/utils/requirements.txt

      # Run the py-allspice self-test script, this will ping the server and verify the API is working
      # Parameters: ${allspice.server_url} and ${allspice.token} are automatic Workflow variables and are used to authenticate the AllSpice API
      - name: "[🔑->🕸️] Test AllSpice API with py-allspice 🔎"
        run: python .allspice/utils/py-allspice-BIST.py --allspice_hub_url ${{ allspice.server_url }}  --allspice_token ${{ allspice.token }}

Now let’s modify the Python script to accept command line parameters.

from allspice import AllSpice
import argparse, sys

parser = argparse.ArgumentParser(
        prog="Allspice_API_BIST", description="Test connection and execution of API actions"
    )

parser.add_argument(
    "--allspice_hub_url",
    help="The URL of your AllSpice Hub instance. Defaults to https://hub.allspice.io.",
)

parser.add_argument(
    "--allspice_token",
    help="Your AllSpice application token. Generate a token: https://hub.allspice.io/user/settings/applications",
)

args = parser.parse_args()

auth_token = args.allspice_token
if auth_token is None:
    print("Please supply a token with --allspice_token <your_token> Generate a token: https://hub.allspice.io/user/settings/applications")
    sys.exit(1)
print(f"Auth token {auth_token}")

if args.allspice_hub_url is None:
    allspice = AllSpice(token_text="https://hub.allspice.io")
else:
    try:
        allspice = AllSpice(
            token_text=auth_token, allspice_hub_url=args.allspice_hub_url
        )
    except Exception as e:
        print("Error")
        sys.exit(1)

print("Finish making connection")
# Test connection and key
print("AllSpice Version: " + allspice.get_version())

# Test private API call
print("API-Token belongs to user: " + allspice.get_user().username)

print("End test")

Adding error handling and using modules to process CLI helps make your scripting more robust. You’re interested in working on your designs, not your code.

Other programming languages

You can use any programming language that can compile and run on Ubuntu Linux LTS.  C/C++ is a good choice as it allows firmware developers to work in their daily language. It is also extremely performant. Javascript is also a popular choice, if you are leveraging your IT team and integrating existing databases and APIs.