Ethanperry/add package copy headers (#30)

Renames several samples, adds headers to files, and cleans up
documentation and readmes.

.github/workflows/callout_build.yml → .github/workflows/device_simulator_build.yml

@@ -1,17 +1,17 @@
-name: callout_build
+name: device-simulator_build
 
 on:
   workflow_dispatch:
   push:
     tags: 
-      - 'v*.*.*-callout'
+      - 'v*.*.*-device-simulator'
 
 jobs:
   call-docker-build:
     uses: ./.github/workflows/docker_build.yml
     with:
-      registry: makocr.azurecr.io/callout
-      file: samples/callout/Dockerfile
+      registry: makocr.azurecr.io/device-simulator
+      file: samples/device-simulator/Dockerfile
       context: .
     secrets:
       azureCredentials: ${{ secrets.AZURE_CREDENTIALS }}

.github/workflows/callout_test.yml → .github/workflows/device_simulator_test.yml

@@ -1,13 +1,13 @@
-name: krill_test
+name: device-simulator_test
 
 on:
   workflow_dispatch:
   push:
     paths:
-      - samples/callout/**
+      - samples/device-simulator/**
 
 jobs:
   call-mage-test:
     uses: ./.github/workflows/mage_tests.yml
     with:
-      workdir: samples/callout/
+      workdir: samples/device-simulator/

.github/workflows/krill_build.yml → .github/workflows/http_grpc_callout_build.yml

@@ -1,17 +1,17 @@
-name: krill_build
+name: http_grpc_callout_build
 
 on:
   workflow_dispatch:
   push:
     tags: 
-      - 'v*.*.*-krill'
+      - 'v*.*.*-http-grpc-callout'
 
 jobs:
   call-docker-build:
     uses: ./.github/workflows/docker_build.yml
     with:
-      registry: makocr.azurecr.io/krill
-      file: samples/krill/Dockerfile
+      registry: makocr.azurecr.io/http-grpc-callout
+      file: samples/http-grpc-callout/Dockerfile
       context: .
     secrets:
       azureCredentials: ${{ secrets.AZURE_CREDENTIALS }}

.github/workflows/krill_test.yml → .github/workflows/http_grpc_callout_test.yml

@@ -1,13 +1,13 @@
-name: krill_test
+name: http_grpc_callout_test
 
 on:
   workflow_dispatch:
   push:
     paths:
-      - samples/krill/**
+      - samples/http-grpc-callout/**
 
 jobs:
   call-mage-test:
     uses: ./.github/workflows/mage_tests.yml
     with:
-      workdir: samples/krill/
+      workdir: samples/http-grpc-callout/

README.md

@@ -1,15 +1,14 @@
-# Azure IoT Operations Dev Toolbox
+# Explore IoT Operations
 
-This repo is the source of tools, samples, and other resources for customers of Azure IoT Operations.
+This repo is the source of tools, samples, tutorials, and other resources for customers of Azure IoT Operations.
 
 ## Features
 
-This project provides the following tools:
+This project provides the following:
 
 * Pre-configured codespace with [K3s](https://k3s.io/) cluster via [K3d](https://k3d.io/)
-* Krill MQTT Data Simulator
-* HTTP Callout Server
-* GRPC Callout Server
+* MQTT Device Simulator
+* HTTP & GRPC Callout Server
 
 > [!IMPORTANT]
 > Codespaces are easy to setup quickly and tear down later, but they're not suitable for performance evaluation or scale testing. For those scenarios, use a validated environment from the official documentation.

docs/ORGANIZATION.md

@@ -1,55 +1,31 @@
-# Toolbox Organization
+# Explore IoT Operations Organization
 
 ## Structure
 
-The AIO toolbox is a collection of several tools for customers of AIO. To keep the project understandable and extensible to future additions, the following conventions should be followed for repository structure.
+Explore IoT Operations is a collection of tools and samples for customers of Azure IoT Operations. To keep the project understandable and extensible to future additions, the following conventions should be followed for repository structure.
 
 ```
-├── lib
-│   ├── library1
+├── lib/
+│   ├── library1/
 │   ├── ...
-│   ├── libraryN
-├── samples
-│   ├── tool1
-│   │   ├── config.yml
-│   │   ├── config.json
+│   ├── libraryN/
+├── samples/
+│   ├── sample1/
 │   ├── ...
-│   ├── toolN
-├── tools
-│   ├── tool1
-│   │   ├── cmd
-│   │   │   ├── main.go
-│   │   ├── pkg
-│   │   │   ├── pkg1
-│   ├── ...
-│   ├── toolN
-├── docker
-│   ├── tool1
-│   │   ├── Dockerfile
-│   ├── ...
-│   ├── toolN
-├── go.mod
-├── go.sum
-├── magefile.go
+│   ├── sampleN/
+├── scripts/
+├── tutorials/
 └── README.md
 ```
 
-__Libraries__ which are shared between multiple tools should be stored in the lib directory. This library can be incorporated into projects beyond AIO tools and such documentation will be available on the _go.dev_ documentation site.
-
-__Samples__ are configuration files which have been created for specific sample usages of a tool. Multiple configuration files can live in each sample folder for different samples which utilize the same tool.
-
-__Tools__ are AIO specific tools which may have their own internal packages stored within the pkg folder. Other top-level folders in each tool are allowed, though it is recommended to minimize the number of top-level folders. Each tool must also have its own cmd directory where the entrypoint is located.
-
-__Dockerfiles__ for relavent docker images are stored for each tool under the docker directory. They are siloed into their own directories for each tool.
-
-__Mage Commands__ are located within the magefile.go. Mage commands should be written in such a way that they apply to any given tool based on a parameter. Mage commands should not be targeted at a specific tool itself. If such a command is required, a magefile within the tool directory should be produced.
+**Libraries** (`./lib`) are shared between multiple tools or samples.
 
-## Linting & Formatting Requirements
+**Samples** (`./samples`) are tools or code samples which can be written in any language. They should be given a descriptive name which adequately describes their purpose, and should include some level of documentation regarding their usage.
 
-Linting and formatting rules are applied to all tools and libraries based on a linting configuration set up and applied via mage commands.
+**Scripts** (`./scripts`) are bash scripts smaller than a tool or sample which are in some way used for setup.
 
-## Example Tool
+**Tutorials** (`./tutorials`) are collections of code and documentation which are used together to provide a step-by-step walkthrough to demonstrate the capabilities of some feature of Azure IoT Operations. These typically serve a more narrow scope than that of a tool or code sample, designed to exercise specific facets of Azure IoT Operations.
 
-Please view the example tool in `tools/example` for an example of how to contribute a new tool to the AIO toolbox.
+## Linting, Formatting, and Testing Requirements
 
-_Note_: tools can be written in any language including minimal tools such as bash scripts. The tools are written in golang in this document for example purposes.
+Linting, formatting, and testing are not required but are highly recommended. The mage library under `./lib/mage` is provided for golang projects and offers some basic commands for linting, formatting, building, testing, and assuring test coverage bars. Comments describe each function within the library. See `./samples/device-simulation/mage.go` for an example of how this library is used.

samples/device-simulator/.gitignore

@@ -0,0 +1,4 @@
+/bin
+cover.tmp.out
+coverage.out
+cover.*

samples/krill/Dockerfile → samples/device-simulator/Dockerfile

@@ -4,18 +4,18 @@ FROM mcr.microsoft.com/oss/go/microsoft/golang:1.21-cbl-mariner2.0 AS build
 
 COPY ./lib /workdir/lib
 
-COPY ./samples/krill /workdir/samples/krill
+COPY ./samples/device-simulator /workdir/samples/device-simulator
 
-WORKDIR /workdir/samples/krill
+WORKDIR /workdir/samples/device-simulator
 
 RUN go mod download
 
 RUN go install github.com/magefile/mage@latest
 
 RUN mage ci
 
-RUN go build -o ./bin/krill ./cmd/krill
+RUN go build -o ./bin/device-simulator ./cmd
 
 EXPOSE 2112
 
-CMD [ "/bin/krill" ]
+CMD [ "/bin/device-simulator" ]

samples/krill/README.md → samples/device-simulator/README.md

@@ -1,32 +1,34 @@
-# Krill
+# Device Simulator
 
 ```
-⠀⠀⠀⠀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣀⣀⣤⣤⣀⠀⠀⠀⠀⠀⠀
-⠀⠀⢀⣀⡙⠻⢶⣶⣦⣴⣶⣶⣶⠾⠛⠛⠋⠉⠉⠉⠉⠙⠃⠀⠀⠀⠀⠀
-⠀⠀⠀⠉⠉⠙⠛⠛⠋⠉⠉⠡⣤⣴⣶⣶⣾⣿⣿⣿⣛⣩⣤⡤⠖⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⢠⣴⣾⠂⣴⣦⠈⣿⣿⣿⣿⣿⣿⠿⠛⣋⠁⠀⠀⠀⠀⠀
-⠀⠀⢀⣼⣿⣶⣄⡉⠻⣧⣌⣁⣴⣿⣿⣿⣿⣿⣿⡿⠛⠁⠀⠀⠀⠀⠀⠀
-⠀⠀⣾⣿⣿⣿⣿⣿⣦⡈⢻⣿⣿⣿⣿⡿⠿⠛⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⡀⢻⣿⣿⣿⣿⣿⣿⣿⡄⠙⠛⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⢠⣷⣄⡉⠻⢿⣿⣿⣿⠏⠠⢶⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⢸⣿⣿⣿⣶⣤⣈⠙⠁⠰⣦⣀⠉⠻⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠘⢿⣿⣿⣿⣿⣿⡇⠠⣦⣄⠉⠳⣤⠈⠛⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⢠⣌⣉⡉⠉⣉⡁⠀⠀⠙⠗⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠹⢿⣿⣿⣿⣿⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠙⠻⣿⣿⠟⢀⣤⡀⠀⠀⠀⠀⠀⠀⣀⣀⣠⣤⣤⣤⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠛⠿⠿⡿⠂⣀⣠⣤⣤⣤⣀⣉⣉⠉⠉⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠙⠛⠛⠛⠛⠋⠉⠉⠁
+ ____          _            _____ _           _     _           
+|    \ ___ _ _|_|___ ___   |   __|_|_____ _ _| |___| |_ ___ ___ 
+|  |  | -_| | | |  _| -_|  |__   | |     | | | | .'|  _| . |  _|
+|____/|___|\_/|_|___|___|  |_____|_|_|_|_|___|_|__,|_| |___|_|  
 ```
 
-Krill is a highly configurable MQTT asset simulator.
+Device Simulator is a highly configurable MQTT asset simulator.
 
 ## Usage
 
-### Krill as K8s Pod
+### Device Simulator as K8s Pod
 
-`kubectl run krill --image=azbluefin.azurecr.io/krill:latest --stdin < config.yml`
+```sh
+# From the root of the device-simulator directory.
+docker build ../.. -f Dockerfile -t <yourcrhere>.azurecr.io/device-simulator:latest
 
-Krill runs as a pod within the desired cluster using the kubectl run command. The configuration of choice is provided via stdin of the krill process within the pod, provided in the command above using `--stdin < config.yml`. Alternative names for a configuration file may be used -- the command simply uses stdin piping to provide krill with an appropriate configuration.
+# Or if running from the root of the explore-iot-operations repository.
+# docker build . -f ./samples/device-simulator/Dockerfile -t <yourcrhere>.azurecr.io/device-simulator:latest
+
+# Push or load your newly built image into your cluster, depending on the k8s setup.
+# docker push <yourcrhere>.azurecr.io/device-simulator:latest # Using AKS + Connected ACR
+# minikube load <yourcrhere>.azurecr.io/device-simulator:latest # Using minikube
+# docker save <yourcrhere>.azurecr.io/device-simulator:latest | k3s ctr images import - # Using K3s
+
+kubectl run device-simulator --image=<yourcrhere>.azurecr.io/device-simulator:latest --stdin < config.yml
+```
+
+Device simulator runs as a pod within the desired cluster using the kubectl run command. The configuration of choice is provided via stdin of the simulator process within the pod, provided in the command above using `--stdin < config.yml`. Alternative names for a configuration file may be used -- the command simply uses stdin piping to provide simulator with an appropriate configuration.
 
 See the example YAML configuration below, with comments describing the various configurable fields.
 
@@ -91,6 +93,31 @@ simulation:
 
 ```
 
+### Device Simulator on the Command Line
+
+#### Method 1
+
+```sh
+# With Golang installed, the device simulator can be run from the cmd folder.
+cd ./cmd
+go run . < config.yml
+# Or by reading in a file instead of stdin:
+# go run . --stdin=false --config=config.yml
+```
+
+#### Method 2
+
+```sh
+# With Golang installed, build a binary of the device simulator.
+go build -o ./bin/device-simulator ./cmd
+./device-simulator < config.yml
+
+# Or by reading in a file instead of stdin:
+# ./device-simulator --stdin=false --config=config.yml
+```
+
+## Configuring a Simulation
+
 ### Configuring Payload Formats
 
 There are currently five supported types of payload formats:
@@ -178,7 +205,7 @@ Example Equations:
 
 ## Metrics
 
-Prometheus metrics are provided by the krill simulator at the port specified in the metrics field of the configuration. The available metrics are:
+Prometheus metrics are provided by the simulator at the port specified in the metrics field of the configuration. The available metrics are:
 
-1. `krill_entity_gauge` - shows the count of each system entity.
-1. `krill_<siteName>_asset_publish_counter` - records the number of messages published, labeled by asset identifier.
+1. `device_simulator_entity_gauge` - shows the count of each system entity.
+1. `device_simulator_<siteName>_asset_publish_counter` - records the number of messages published, labeled by asset identifier.

samples/krill/cmd/krill/main.go → samples/device-simulator/cmd/main.go

@@ -1,3 +1,6 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
 package main
 
 import (
@@ -11,24 +14,24 @@ import (
 
 	"github.com/explore-iot-ops/lib/env"
 	"github.com/explore-iot-ops/lib/logger"
-	"github.com/explore-iot-ops/samples/krill/components/broker"
-	"github.com/explore-iot-ops/samples/krill/components/client"
-	"github.com/explore-iot-ops/samples/krill/components/edge"
-	"github.com/explore-iot-ops/samples/krill/components/formatter"
-	"github.com/explore-iot-ops/samples/krill/components/limiter"
-	"github.com/explore-iot-ops/samples/krill/components/node"
-	"github.com/explore-iot-ops/samples/krill/components/observer"
-	"github.com/explore-iot-ops/samples/krill/components/outlet"
-	"github.com/explore-iot-ops/samples/krill/components/provider"
-	"github.com/explore-iot-ops/samples/krill/components/publisher"
-	"github.com/explore-iot-ops/samples/krill/components/registry"
-	"github.com/explore-iot-ops/samples/krill/components/renderer"
-	"github.com/explore-iot-ops/samples/krill/components/site"
-	"github.com/explore-iot-ops/samples/krill/components/subscriber"
-	"github.com/explore-iot-ops/samples/krill/components/topic"
-	"github.com/explore-iot-ops/samples/krill/components/tracer"
-	"github.com/explore-iot-ops/samples/krill/lib/exporter"
-	"github.com/explore-iot-ops/samples/krill/lib/krill"
+	"github.com/explore-iot-ops/samples/device-simulator/components/broker"
+	"github.com/explore-iot-ops/samples/device-simulator/components/client"
+	"github.com/explore-iot-ops/samples/device-simulator/components/edge"
+	"github.com/explore-iot-ops/samples/device-simulator/components/formatter"
+	"github.com/explore-iot-ops/samples/device-simulator/components/limiter"
+	"github.com/explore-iot-ops/samples/device-simulator/components/node"
+	"github.com/explore-iot-ops/samples/device-simulator/components/observer"
+	"github.com/explore-iot-ops/samples/device-simulator/components/outlet"
+	"github.com/explore-iot-ops/samples/device-simulator/components/provider"
+	"github.com/explore-iot-ops/samples/device-simulator/components/publisher"
+	"github.com/explore-iot-ops/samples/device-simulator/components/registry"
+	"github.com/explore-iot-ops/samples/device-simulator/components/renderer"
+	"github.com/explore-iot-ops/samples/device-simulator/components/site"
+	"github.com/explore-iot-ops/samples/device-simulator/components/subscriber"
+	"github.com/explore-iot-ops/samples/device-simulator/components/topic"
+	"github.com/explore-iot-ops/samples/device-simulator/components/tracer"
+	"github.com/explore-iot-ops/samples/device-simulator/lib/exporter"
+	"github.com/explore-iot-ops/samples/device-simulator/lib/external"
 	"gopkg.in/yaml.v3"
 
 	"github.com/prometheus/client_golang/prometheus"
@@ -45,7 +48,7 @@ func main() {
 
 func run() error {
 
-	fmt.Print(krill.Krill)
+	fmt.Print(external.Logo)
 
 	ctx := context.Background()
 
@@ -67,8 +70,8 @@ func run() error {
 		unmarshal = json.Unmarshal
 	}
 
-	configReader := env.New[krill.Configuration](
-		func(cr *env.ConfigurationReader[krill.Configuration]) {
+	configReader := env.New[external.Configuration](
+		func(cr *env.ConfigurationReader[external.Configuration]) {
 			cr.Unmarshal = unmarshal
 			if *flags["stdin"].(*bool) {
 				cr.ReadFile = func(_ string) ([]byte, error) {
@@ -186,7 +189,7 @@ func run() error {
 	topicService := topic.NewService(topicStore, registryStore)
 	tracerService := tracer.NewService(tracerStore, registryStore)
 
-	builder := krill.New(
+	builder := external.New(
 		brokerService,
 		clientService,
 		edgeService,
@@ -205,7 +208,7 @@ func run() error {
 		tracerService,
 	)
 
-	lg.Printf("parsing krill configuration")
+	lg.Printf("parsing external configuration")
 
 	err = builder.Parse(configuration.Simulation)
 	if err != nil {