diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml new file mode 100644 index 000000000..640cf614d --- /dev/null +++ b/.github/workflows/public-site-test.yml @@ -0,0 +1,251 @@ +name: "Test Site" + +on: + workflow_dispatch: + pull_request: + branches: [ "develop" ] + +jobs: + build: + runs-on: ubuntu-latest + environment: sandbox + steps: + + # Clone current repo + - name: Checkout + uses: actions/checkout@v3 + with: + path: src + # ref: develop # <-- required to deploy beta docs + + # npm install + - name: npm install + working-directory: ./src + run: | + npm install + + # compress the images + - name: Compress Images + working-directory: ./src + run: | + node ./scripts/compress.js ./ + + # Clone all the Meadow dependencies adjacent for DocFX build use. + - name: Checkout Meadow.Units side-by-side + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Units + path: Meadow.Units + ref: main + - name: Checkout Meadow.Logging side-by-side + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Logging + path: Meadow.Logging + ref: main + - name: Checkout Meadow.Contracts side-by-side + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Contracts + path: Meadow.Contracts + ref: main + - name: Checkout Meadow.Modbus side-by-side + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Modbus + path: Meadow.Modbus + ref: main + - name: Checkout Meadow.Foundation side-by-side + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation + path: Meadow.Foundation + ref: main + - name: Checkout Meadow.Core side-by-side + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Core + path: Meadow.Core + ref: main + - name: Checkout MQTTnet side-by-side + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/MQTTnet + path: MQTTnet + ref: master + - name: Checkout Meadow side-by-side + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + # Private repo requires token access; rest are public repos. + token: ${{ secrets.CI_ACCESS_TOKEN }} + repository: WildernessLabs/Meadow + path: Meadow + ref: main + # Clone more Meadow-related repos for API docs generation (via DocFX). + - name: Checkout Meadow.Foundation.CompositeDevices into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.CompositeDevices + path: Meadow.Foundation.CompositeDevices + ref: main + - name: Checkout Meadow.Foundation.Grove into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.Grove + path: Meadow.Foundation.Grove + ref: main + - name: Checkout Meadow.Foundation.FeatherWings into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.FeatherWings + path: Meadow.Foundation.FeatherWings + ref: main + - name: Checkout Meadow.Foundation.mikroBUS into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.mikroBUS + path: Meadow.Foundation.mikroBUS + ref: main + + # # Set up for DocFX + - name: Setup .NET Core SDK 7.0.x + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/setup-dotnet@v3 + with: + dotnet-version: | + 7.0.x + - name: Setup NuGet + if: contains(github.event.pull_request.title, '[build-api]') + uses: Nuget/setup-nuget@v1.2.0 + - name: Install DocFX globally + if: contains(github.event.pull_request.title, '[build-api]') + run: | + dotnet tool install --global docfx + - name: Install DocFxMarkdownGen + if: contains(github.event.pull_request.title, '[build-api]') + run: | + dotnet tool install --global DocFxMarkdownGen + - name: Run DocFX + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src/docfx + run: | + docfx docfx.json + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow + if: contains(github.event.pull_request.title, '[build-api]') + # dfmg uses config.yaml for input/output paths + # Currently config has to be limited to `docfx/api/Meadow`, which means we need to figure out a way to run it for all the other /api directories. + # We might be able to set `env:DFMG_YAML_PATH` and `env:DFMG_OUTPUT_PATH` to the correct values for each repo, to generate them all before merging them together. + # One option is setting `env: {whatever}` via Actions syntax (https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrun). + working-directory: ./src/docfx/dfmg/Meadow + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src/docfx/dfmg/Meadow.Foundation + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.CompositeDevices + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src/docfx/dfmg/Meadow.Foundation.CompositeDevices + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.FeatherWings + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src/docfx/dfmg/Meadow.Foundation.FeatherWings + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.Grove + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src/docfx/dfmg/Meadow.Foundation.Grove + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.mikroBUS + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src/docfx/dfmg/Meadow.Foundation.mikroBUS + run: | + dfmg + + # let's add correct slugs. They are important, because things won't build if they dont have "slug: /docs/api/..." + - name: Update slugs in frontmatter. + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src + run: | + node ./scripts/update-frontmatter.js + + # Now we need to take all of the generated class/api reference documentation, and merge + # it into the api-overrides content + - name: Merge api docs together + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src + run: | + node ./scripts/merge-api-overrides.js Meadow.Foundation && + node ./scripts/merge-api-overrides.js Meadow.Foundation.FeatherWings && + node ./scripts/merge-api-overrides.js Meadow.Foundation.Grove && + node ./scripts/merge-api-overrides.js Meadow.Foundation.mikroBUS + + # Let's put the api files where they belong + - name: Copy api files to content locations + if: contains(github.event.pull_request.title, '[build-api]') + working-directory: ./src + run: | + node ./scripts/update-frontmatter.js && + node ./scripts/copy-api.js + + # Fun. Docusaurus isn't resolving the links correctly from many + # of the files output from dfmg. This script should help with that. + - name: Fix api broken links + working-directory: ./src + run: | + node ./scripts/api-broken-link-fixer.js ./docs/api/ + + # - name: Fix Meadow.Foundation periphs broken links + # working-directory: ./src + # run: | + # node ./scripts/meadow-foundation-broken-link-fixer.js + + #docusaurus build + - name: Use Node.js + uses: actions/setup-node@v3 + with: + node-version: 18 + cache: 'npm' + # Tell Node.js to look for the package-lock.json file in the cloned repo location rather than root. + cache-dependency-path: src/package-lock.json + - name: Docusaurus Build and Deploy + working-directory: ./src + run: | + npm run build + - uses: bacongobbler/azure-blob-storage-upload@main + with: + source_dir: './src/build' + container_name: '$web' + connection_string: ${{ secrets.BLOB_CONNECTIONSTRING }} + overwrite: 'true' + #sync: 'true' + + # Post a comment on the pull request + - name: Post comment on pull request + if: github.event_name == 'pull_request' + uses: actions/github-script@v6 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: 'Thank you for having the patience of Asclepius. Your test site, https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/ is ready to view.' + }) \ No newline at end of file diff --git a/.github/workflows/publish-site-beta.yml b/.github/workflows/publish-site-beta.yml index 0a13bbf26..d97918422 100644 --- a/.github/workflows/publish-site-beta.yml +++ b/.github/workflows/publish-site-beta.yml @@ -93,6 +93,13 @@ jobs: path: Meadow ref: main # Clone more Meadow-related repos for API docs generation (via DocFX). + - name: Checkout Meadow.Foundation.CompositeDevices into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.CompositeDevices + path: Meadow.Foundation.CompositeDevices + ref: main - name: Checkout Meadow.Foundation.Grove into DocFX-expected Source location if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 diff --git a/.github/workflows/publish-site-prod.yml b/.github/workflows/publish-site-prod.yml index 6d2371968..364da076c 100644 --- a/.github/workflows/publish-site-prod.yml +++ b/.github/workflows/publish-site-prod.yml @@ -85,6 +85,12 @@ jobs: path: Meadow ref: main # Clone more Meadow-related repos for API docs generation (via DocFX). + - name: Checkout Meadow.Foundation.CompositeDevices into DocFX-expected Source location + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.CompositeDevices + path: Meadow.Foundation.CompositeDevices + ref: main - name: Checkout Meadow.Foundation.Grove into DocFX-expected Source location uses: actions/checkout@v3 with: diff --git a/docfx/api/Meadow.Foundation.CompositeDevices/index.md b/docfx/api/Meadow.Foundation.CompositeDevices/index.md index 7aba47520..8fb0f4421 100644 --- a/docfx/api/Meadow.Foundation.CompositeDevices/index.md +++ b/docfx/api/Meadow.Foundation.CompositeDevices/index.md @@ -1 +1,2 @@ ## Meadow.Foundation.CompositeDevices API Reference Documentation +hi \ No newline at end of file diff --git a/docs/Meadow/Getting_Started/Assemble_Meadow/index.md b/docs/Meadow/Getting_Started/Assemble_Meadow/index.md index 5fe382f39..d348cf6e9 100644 --- a/docs/Meadow/Getting_Started/Assemble_Meadow/index.md +++ b/docs/Meadow/Getting_Started/Assemble_Meadow/index.md @@ -43,7 +43,7 @@ Meadow has battery connector on the right side of the device. For this reason, y ![Breadboard, Protoboard and Meadow](./MeadowDev_Places.jpg) -Remove the plastic sticker cover under the breadboard and stick it to the protoboard as firm and straight as possible. +Remove the plastic sticker cover under the breadboard and stick it to the protoboard as firm and straight as possible. If you plan to use the outer-most holes to mount your Meadow kit to something else, make sure to keep the holes clear with enough room to add screws or standoffs. ![Protoboard with breadboard mounted and Meadow adjacent with mounting hardware.](./MeadowDev_Breadboard.jpg) diff --git a/docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md b/docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md index d01a1c7c5..003f7c145 100644 --- a/docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md +++ b/docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md @@ -7,6 +7,10 @@ subtitle: Flashing the Meadow with the latest OS via Meadow.CLI When you receive your Meadow board, it will need to have the latest Meadow.OS uploaded, or _flashed_, to it. +> NOTE: Communicating with the Meadow board for updates and deployments requires a quality USB cable with data lines. Some USB charging cables only have power lines connected internally or have poor construction that may not properly support communication. Power-only cables will not work for communicating with a device. And poorly constructed cables may fail during various updating and deploying attempts. Make sure to find a quality USB cable with data lines if your Meadow device is not recognized or communication errors occur. +> +> Additionally, if you have your Meadow device connected through a USB hub without a dedicated power supply, it may not provide enough power to the device. In this case, connect the Meadow device directly to your computer. + diff --git a/docs/Meadow/Getting_Started/Setup/index.md b/docs/Meadow/Getting_Started/Setup/index.md index 1672f3f3e..d6dffddb1 100644 --- a/docs/Meadow/Getting_Started/Setup/index.md +++ b/docs/Meadow/Getting_Started/Setup/index.md @@ -4,11 +4,4 @@ title: Setup subtitle: Guides and documentation for Meadow --- -# Configuring the Meadow Build Environment - -1. [Connect Meadow to the ST-Link V2](stlink/) - * Configure Your Development Environment: - * [macOS](macos/) - * [Windows](Windows/) - -## [Next - Deploy Meadow OS](/Meadow/Getting_Started/Deploying_Meadow%2EOS/) \ No newline at end of file +This content has [moved](/Meadow/Getting_Started/). diff --git a/docs/Meadow/Meadow.Cloud/Logs_Events/index.md b/docs/Meadow/Meadow.Cloud/Logs_Events/index.md index f1dcefe93..71d38b298 100644 --- a/docs/Meadow/Meadow.Cloud/Logs_Events/index.md +++ b/docs/Meadow/Meadow.Cloud/Logs_Events/index.md @@ -6,25 +6,27 @@ subtitle: Getting started with logs and events ## Enabling CloudLogger -Today, logging output through `Resolver.Log.Info("foo bar");` writes to the console. This is great if you are working locally, connected to the device, but not so much when the device is deployed out in the field. Fortunately, getting the same logs in Meadow.Cloud is really simple. +Today, logging output through `Resolver.Log.Info("foo bar")` writes to the console. This is great if you are working locally, connected to the device, but not so much when the device is deployed out in the field. Fortunately, you can also send the same logs to Meadow.Cloud with a few extra steps. -Setting up logs and events requires the following update in `app.config.yaml`: +1. Install the [**Meadow.Logging.LogProviders** NuGet package](https://www.nuget.org/packages/Meadow.Logging.LogProviders) into your project for access to the `CloudLogger` class. -```yaml -MeadowCloud: - Enabled: true -``` +1. Enable Meadow.Cloud logging in your project's `app.config.yaml`: -Then, all you need to register a new `CloudLogger`: + ```yaml + MeadowCloud: + Enabled: true + ``` -```csharp -public override async Task Initialize() -{ - var cloudLogger = new CloudLogger(); - Resolver.Log.AddProvider(cloudLogger); - ... -} -``` +1. Register a new `CloudLogger` as a logging provider: + + ```csharp + public override async Task Initialize() + { + var cloudLogger = new CloudLogger(); + Resolver.Log.AddProvider(cloudLogger); + ... + } + ``` Once `CloudLogger` is registered, any logging done through `Resolver.Log` automatically gets recorded in Meadow.Cloud. Any logging done while the device is disconnected get stored locally and sent to Meadow.Cloud once a network connected is established. diff --git a/docs/Meadow/Meadow.Foundation/Getting_Started/index.md b/docs/Meadow/Meadow.Foundation/Getting_Started/index.md index 854845682..cf9eac497 100644 --- a/docs/Meadow/Meadow.Foundation/Getting_Started/index.md +++ b/docs/Meadow/Meadow.Foundation/Getting_Started/index.md @@ -6,7 +6,7 @@ subtitle: Meadow.Foundation ## Hello, World! -1. [Configure your Meadow development environment](../../Getting_Started/MCUs/F7_Feather/index.md). +1. [Configure your Meadow development environment](../../Getting_Started/index.md). 1. Create a new C# Meadow Application project, name it `HelloPulsy`. 1. Plug the longer leg (anode) of a blue LED into pin `13` and the other leg into `GND`: diff --git a/docs/Meadow/Meadow.OS/Networking/index.md b/docs/Meadow/Meadow.OS/Networking/index.md index 2d8b0cb5d..2d6840dec 100644 --- a/docs/Meadow/Meadow.OS/Networking/index.md +++ b/docs/Meadow/Meadow.OS/Networking/index.md @@ -124,17 +124,17 @@ If you're using an [Dual, Switching Ethernet Add-on module](https://store.wilder Network: Interfaces: - Name: Ethernet - UseDHCP: false - IPAddress: 192.168.1.60 - NetMask: 255.255.255.0 - Gateway: 192.168.1.254 -# - Name: Ethernet -# UseDHCP: true + UseDHCP: true + # IPAddress: 192.168.1.60 + # NetMask: 255.255.255.0 + # Gateway: 192.168.1.254 DefaultInterface: Ethernet ... ``` -Optionally you can set the `UseDHCP: true` to get an IP Address automatically. If `DefaultInterface` is not set on the config file, it will default to WiFi. +Optionally you can set the `UseDHCP: false` to use an static IP Address. In this case, please configure your `IpAddress`, `NetMask`, and `Gateway` correctly, ensuring the `IPAddress` is within your local network and not already in use. + +If `DefaultInterface` is not set on the config file, it will default to WiFi. diff --git a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/I2C/index.md b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/I2C/index.md index 816362ad5..bc5d21824 100644 --- a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/I2C/index.md +++ b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/I2C/index.md @@ -62,10 +62,10 @@ II2cBus i2cBus = Device.CreateI2cBus(); ## Working with I2C Peripherals -Once the I2C Bus has been created, peripherals can be created by passing in the I2C Bus and the address of the peripheral: +Once the I2C Bus has been created, you create a communications object to send data through the I2C Bus on a specific address: ```csharp -II2cPeripheral i2cPeripheral = new I2cPeripheral(i2cBus, 39); +II2cCommunications i2cComms = new I2cCommunications(i2cBus, 39); ``` ### Peripheral Communication @@ -73,11 +73,11 @@ II2cPeripheral i2cPeripheral = new I2cPeripheral(i2cBus, 39); Generally, you won't need to handle low-level I2C peripheral communication directly, as the peripheral drivers in Meadow.Foundation expose high level APIs for working with their features. However, if you're creating a new driver, or want to talk to a peripheral directly, there are a number of communications methods exposed via the [`IByteCommunications`](/docs/api/Meadow/Meadow.Hardware/IByteCommunications/) interface, which I2C peripherals implement. Among these are methods to read and write bytes directly to the device as well as read and write to memory registers on the device: ```csharp -i2cPeripheral.WriteByte(0x01); +i2cComms.Write(0x01); ``` These methods are also available via the I2C bus, but require the address of the device to be explicitly passed: ```csharp -i2cBus.WriteByte(i2cPeripheral.Address, 0x01); +i2cBus.Write(i2cComms.Address, new byte[] { 0x01 }); ``` diff --git a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md index 66dc59f21..0ae7370d4 100644 --- a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md +++ b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md @@ -56,11 +56,11 @@ ISpiBus spiBus = Device.CreateSpiBus(); ## Working with SPI Peripherals -Once the SPI Bus has been created, peripherals can be created by passing in the SPI Bus and the `IDigitalOutputPort` that is connected to the chip select on the peripheral: +Once the SPI Bus has been created, peripherals can be created by passing in the SPI Bus, the `IDigitalOutputPort`, and the bus speed of the SPI bus that is connected to the chip select on the peripheral: ```csharp -IDigitalOutputPort spiPeriphChipSelect = Device.CreateDigitalOutputPort(Device.Pins.D03); -ISpiPeripheral spiPeriph = new SpiPeripheral(spiBus, spiPeriphChipSelect); +IDigitalOutputPort spiCommsChipSelect = Device.CreateDigitalOutputPort(Device.Pins.D03); +ISpiCommunications spiComms = new SpiCommunications(spiBus, spiPeriphChipSelect, new(10_000, Frequency.UnitType.Kilohertz)); ``` ### Peripheral Communication @@ -68,11 +68,11 @@ ISpiPeripheral spiPeriph = new SpiPeripheral(spiBus, spiPeriphChipSelect); Generally, you won't need to handle low-level SPI peripheral communication directly, as the peripheral drivers in Meadow.Foundation expose high level APIs for working with their features. However, if you're creating a new driver, or want to talk to a peripheral directly, there are a number of communications methods exposed via the [`IByteCommunications`](/docs/api/Meadow/Meadow.Hardware/IByteCommunications/) interface, which SPI peripherals implement. Among these are methods to read and write bytes directly to the device as well as read and write to memory registers on the device: ```csharp -spiPeriph.WriteByte(0x01); +spiComms.WriteByte(0x01); ``` -These methods are also available via the SPI bus, but require the chip select port of the device to be explicitly passed: +A similar `Write` method is also available via the SPI bus, but require the chip select port of the device to be explicitly passed: ```csharp -spiBus.WriteByte(spiPeriph.ChipSelect, 0x01); +spiBus.Write(spiCommsChipSelect, new byte[] { 0x01 }); ``` diff --git a/docs/Meadow/Release_Notes/v1/index.md b/docs/Meadow/Release_Notes/v1/index.md index 41a3cfa8d..e7b171359 100644 --- a/docs/Meadow/Release_Notes/v1/index.md +++ b/docs/Meadow/Release_Notes/v1/index.md @@ -10,6 +10,41 @@ subtitle: Release Notes * [Meadow.CLI](/Meadow/Meadow_Tools/Meadow_CLI/) * [Meadow.OS](/Meadow/Getting_Started/Deploying_Meadow%2EOS/) +## v1.12.8.0 + +### Meadow.OS + +* This is a managed stack release only. No OS changes. + +### Meadow.Core + +* Added WiFi scanning support to Meadow.Linux +* Bug fixes to I2C reads in Meadow.Linux +* Improved app crash logging +* Bug fixes in F7 PWMs +* Added new `IApp` pattern for platforms like ProjectLab +* Bug fix in app.config parser +* Bug fixes in MicroLayout (positioning inside a parent) +* Bug fix in SpiComms ReadRegister +* Bug fixes in Gnss parsing +* Improved network adapter events for wired, cell, and wifi +* Added NTP support to Cell adapter + +#### Breaking changes + +* PWMs now use Units for Duration and Frequency instead of the ambiguous float +* Renamed [Ft232h](https://www.nuget.org/packages/Meadow.Foundation.ICs.IOExpanders.Ft232h/) nuget package to [Ftxxxx](https://www.nuget.org/packages/Meadow.Foundation.ICs.IOExpanders.Ftxxxx) + +### Meadow.Foundation + +* Added `JsonPropertyName` to `MicroJson` +* Added support for `TimeSpan`, nullables and `List` to `MicroJson` +* Added `ResistiveTankLevelSender` + +#### Breaking changes + +* [Servos](https://www.nuget.org/packages/Meadow.Foundation.Servos) have been refactored, fixed and improved. The previous Servo API was both confusing and likely not working. + ## v1.12.2 ### Meadow.OS