From 708856bcf0f00b95fede077a8c7b9abc5806c94b Mon Sep 17 00:00:00 2001 From: Michael Brown Date: Fri, 17 Feb 2023 22:18:55 -0800 Subject: [PATCH] added api integration help page --- Binner/Binner.Web/ClientApp/src/App.js | 3 +- .../src/pages/help/ApiIntegrations.js | 116 ++++++++++++++++++ .../ClientApp/src/pages/help/Home.js | 1 + .../ClientApp/src/pages/help/Scanning.js | 34 +---- .../ClientApp/src/pages/help/help.css | 43 +++++++ 5 files changed, 164 insertions(+), 33 deletions(-) create mode 100644 Binner/Binner.Web/ClientApp/src/pages/help/ApiIntegrations.js diff --git a/Binner/Binner.Web/ClientApp/src/App.js b/Binner/Binner.Web/ClientApp/src/App.js index 59a799ee..38dcf1a0 100644 --- a/Binner/Binner.Web/ClientApp/src/App.js +++ b/Binner/Binner.Web/ClientApp/src/App.js @@ -31,7 +31,7 @@ import { ResistorColorCodeCalculator } from "./pages/tools/ResistorColorCodeCalc import { VoltageDividerCalculator } from "./pages/tools/VoltageDividerCalculator"; import { Help } from './pages/help/Home'; import { Scanning } from './pages/help/Scanning'; - +import { ApiIntegrations } from './pages/help/ApiIntegrations'; export default class App extends Component { static displayName = App.name; @@ -87,6 +87,7 @@ export default class App extends Component { /> } /> } /> + } /> diff --git a/Binner/Binner.Web/ClientApp/src/pages/help/ApiIntegrations.js b/Binner/Binner.Web/ClientApp/src/pages/help/ApiIntegrations.js new file mode 100644 index 00000000..5fd7ca8f --- /dev/null +++ b/Binner/Binner.Web/ClientApp/src/pages/help/ApiIntegrations.js @@ -0,0 +1,116 @@ +import React from 'react'; +import { Link, useNavigate } from 'react-router-dom'; +import { Segment, Breadcrumb, Image } from "semantic-ui-react"; +import "./help.css"; + +export const ApiIntegrations = () => { + const navigate = useNavigate(); + return ( +
+ + navigate('/')}>Home + + navigate('/help')}>Help + + Api Integrations + +

How to configure API Integrations

+ + +

Overview

+

+ Binner currently supports Binner Swarm, Digikey, Mouser, Octopart and AliExpress. For standalone installations, you will need to obtain your own API keys to enable these features. It's easy to obtain them but be aware Octopart is not free so you may want to avoid using it. Alternatively you can use Binner.io if you do not wish to worry about configuring external API's. +

+

+ Integrations enable features such as automatic part metadata lookup, datasheet retrieval and automatic importing parts from your orders. To get the best out of Binner, it is a good idea to sign up for Digikey and Mouser API keys at a minimum however they are not required. +

+

+ Configuration values can be found in appsettings.json alongside the Binner executable. +

+ + +

Configuring Binner Swarm API

+ +

+ Binner comes with free Swarm API support built-in. Swarm is an aggregate of part information that includes parametrics, datasheets, product images, pinouts and schematics. It is a new service, so content is still being expanded and indexed so a lot more data will be coming in the near future. There is a limit on how many Swarm requests can be made per hour/day - if you feel you need larger limits you can signup for a free or paid account at https://binner.io/swarm and your limits are increased accordingly. +

+ +

Settings example

+ 
// appsettings.json

+{JSON.stringify({ Integrations: {
+    Swarm: {
+			Enabled: true,
+			ApiKey: "",
+			ApiUrl: "https://swarm.binner.io",
+    },
+},}, null, 2)}
 + +

Configuring DigiKey API

+

+ Visit https://developer.digikey.com and sign up for a free developer account. You will be asked to create an App which will come with a ClientId and ClientSecret and needs to be set in the appsettings.json under the DigiKey configuration section. +

+ +
Creating an App
+ +
+ The DigiKey Api uses oAuth with postbacks so this must be configured in your DigiKey developer account. DigiKey calls this a Callback URL, while in Binner this is the oAuthPostbackUrl. This can be safely set to https://localhost:8090/Authorization/Authorize in both systems. It is not called by their servers, but rather by the web UI so it does not need to resolve to an external IP and requires no firewall settings. It must be set to exactly the same value on both systems. +
+ DigiKey Callback URL + Figure 1. DigiKey's api settings, located in the DigiKey api developers portal +
+ +
+ +
You will want to enable API access for the Product Information, Order Support, and Barcode Apis.
+ +
Sandbox
+ +

If you wish to use the DigiKey sandbox rather than their production API, you can specify the ApiUrl to use https://sandbox-api.digikey.com. Otherwise, you can leave it set to https://api.digikey.com

+ +

Settings example

+ 
// appsettings.json

+{JSON.stringify({ Integrations: {
+    Digikey: {
+			Enabled: true,
+			ClientId: "KsGAFuZGErn4zgvFDI9ux4nW3vZ63H3r",
+			ClientSecret: "IAbQsT4GCnagahrH",
+			oAuthPostbackUrl: "https://localhost:8090/Authorization/Authorize",
+			ApiUrl: "https://api.digikey.com",
+    },
+},}, null, 2)}
 + +

Configuring Mouser API

+

Visit https://www.mouser.com/api-hub and sign up for a free developer account. Mouser requires you to sign up for each API product you wish to use. Currently, Binner supports both the Search API and Order API so sign up for those two APIs separately. Once you have an API key for each, set those in the appsettings.json under the Mouser configuration section.

+ +

Settings example

+ 
// appsettings.json

+{JSON.stringify({ Integrations: {
+    Mouser: {
+			Enabled: true,
+			ApiKeys: {
+				SearchApiKey: "84e40c37-99de-4990-86c2-290749dc7f52",
+				OrderApiKey: "2d1a00d7-16fd-4979-b7e3-5ca384711ab2",
+				CartApiKey: ""
+			},
+			ApiUrl: "https://api.mouser.com"
+    },
+},}, null, 2)}
 + +

Configuring Octopart API

+

Visit https://octopart.com/api/home and sign up for a developer account. Please note that Octopart API is not free to use so you may opt to skip this one. They don't advertise pricing until you start using the API (sneaky), but if you already have a key it can be used for additional datasheet support. If you do not wish to use it Digikey and Mouser will be used to access datasheets for parts, as well as the free Binner datasheet API.

+ +

Settings example

+ 
// appsettings.json

+{JSON.stringify({ Integrations: {
+    Octopart: {
+			Enabled: true,
+			ApiKey: "b3h5632j245jh5521426",
+			ApiUrl: "https://octopart.com"
+    },
+},}, null, 2)}
 + + + +
+ ); +} diff --git a/Binner/Binner.Web/ClientApp/src/pages/help/Home.js b/Binner/Binner.Web/ClientApp/src/pages/help/Home.js index 61201991..15e7275a 100644 --- a/Binner/Binner.Web/ClientApp/src/pages/help/Home.js +++ b/Binner/Binner.Web/ClientApp/src/pages/help/Home.js @@ -24,6 +24,7 @@ export const Help = () => {
  • Barcode Scanning

    Learn more about what types of features are available using a handheld barcode scanner.

    • +
  • Api Integrations

    Configuring Api integrations are an important part of using Binner effectively.

  • Wiki

    Get more help from the wiki on GitHub

diff --git a/Binner/Binner.Web/ClientApp/src/pages/help/Scanning.js b/Binner/Binner.Web/ClientApp/src/pages/help/Scanning.js index 86c59f01..8eac4279 100644 --- a/Binner/Binner.Web/ClientApp/src/pages/help/Scanning.js +++ b/Binner/Binner.Web/ClientApp/src/pages/help/Scanning.js @@ -79,40 +79,10 @@ export const Scanning = () => {

Mouser

-

- Mouser uses different types of barcodes for it's various paperwork and labeling. Invoices use a standard code-128 barcode which can be scanned on the Order Import page.

- Parts use a 2D DotMatrix barcode so you must have a scanner that supports 2D barcodes. +

+ Mouser barcode scanning support is coming soon! Look for it in the next feature release.

-
Scanning Parts
- By scanning the 2D Dotmatrix barcode on a part label you can:

-
    -
  • Search for parts in your inventory on the Search page
    • -
  • Add new parts to your inventory on the Add Inventory page
    • -
  • Bulk import new parts on the Add Inventory page
    • -
- -
- Mouser DotMatrix 2D Barcode - Example 1. This is a 2D DotMatrix barcode on a standard Mouser part label. -
- -
Importing Orders
- -

- On the Order Import page you can scan one of your past orders to import all parts in the order at once.
- To do so, you will need the Mouser packing list for your order. The invoice doesn't contain the barcodes you want, however you can type in the Sales Order Number manually easily as well. - -

- -
- Mouser DotMatrix 2D Barcode - Example 2. There are multiple 1D code-128 barcodes, and several 2D DotMatrix barcodes on a standard Mouser packing list. -
- -

The Sales Order number can be scanned (top right) to import the entire - or parts of an order. You can also scan the 2D DotMatrix barcodes which provide the same information.

-

Additionally, each itemized part can be scanned in the packing list but this is only supported on the Add Inventory page. Note there is a barcode for both the part as well as a smaller barcode for its quantity.

- diff --git a/Binner/Binner.Web/ClientApp/src/pages/help/help.css b/Binner/Binner.Web/ClientApp/src/pages/help/help.css index f9a7b618..ba166a7f 100644 --- a/Binner/Binner.Web/ClientApp/src/pages/help/help.css +++ b/Binner/Binner.Web/ClientApp/src/pages/help/help.css @@ -167,4 +167,47 @@ img.helpvideo { display: block; border: 1px dotted #666; padding: 5px; +} + +textarea { + width: 75%; + height: 200px; +} + +code { + background: #f4f4f4; + border: 1px solid #ddd; + border-left: 3px solid #f36d33; + color: #666; + page-break-inside: avoid; + font-family: monospace; + font-size: 15px; + line-height: 1.6; + margin-bottom: 1.6em; + max-width: 100%; + padding: 1em 1.5em; + display: block; + word-wrap: break-word !important; + white-space: pre-line !important; +} + +pre { + white-space: pre !important; +} + +p > b, li > b, .bullet > b { + font-weight: 600; + color: rgb(0, 115, 204); +} + +li { + padding: 10px 0; + margin-left: 30px; +} + +.bullet { + border-left: 2px solid #3340f3; + padding: 10px; + margin-left: 30px; + margin-bottom: 15px; } \ No newline at end of file