@rdlabo/capacitor-brotherprint 8.1.1-beta.pr40.shae90134023d21 → 8.1.1

package/README.md

@@ -1,55 +1,272 @@
 # @rdlabo/capacitor-brotherprint
 
-Capacitor Brother Print binds the native Brother Print SDK for iOS and Android so you can search supported Brother label printers and print images from a Capacitor app.
+Capacitor Brother Print is a native Brother Print SDK implementation for iOS & Android. Support These models.
 
-**This plugin is still in the RC (release candidate) phase.** iOS requires **Swift Package Manager** and a minimum of **iOS 15**. The Brother Print SDK is not compatible with CocoaPods for this plugin.
+**This plugin is still in the RC (release candidate) phase.**
 
-<!-- rdlabo-docs-omit -->
-**Documentation:** [Read the full documentation](https://docs.rdlabo.dev/projects/capacitor-brotherprint)
-<!-- /rdlabo-docs-omit -->
-
-## Install
-
-```
-npm install @rdlabo/capacitor-brotherprint
-```
-
-For SDK placement, SPM layout, and permissions, see [Installation](https://docs.rdlabo.dev/projects/capacitor-brotherprint/docs/installation).
-
-## Print your first label
-
-1. [Installation](https://docs.rdlabo.dev/projects/capacitor-brotherprint/docs/installation) — npm install, place the Brother SDK, permissions, then `npx cap sync`.
-2. [Search](https://docs.rdlabo.dev/projects/capacitor-brotherprint/docs/search) — register `onPrinterAvailable`, keep the discovered channel, run Wi-Fi (or other) search.
-3. [Print](https://docs.rdlabo.dev/projects/capacitor-brotherprint/docs/print) — print with that channel, a supported model/label, and a real base64 image you prepare.
-4. [Events](https://docs.rdlabo.dev/projects/capacitor-brotherprint/docs/events) — print success and error listeners in more detail.
+**Brother Print SDK is incompatible with CocoaPods and Minimum Developments iOS 14 and is not working at this time, please use Swift Package Manager.**
 
 ## Supported models
 
-Each product link is an Amazon affiliate link. Purchases through these links help support development costs.
+Each product link is an Amazon affiliate link. If you choose to make a purchase through these links, it would be greatly appreciated and **would help** support development costs. Thank you!
 
 | Product                               | Model        | iOS/WiFi | iOS/BT | iOS/BLE | Android/USB | Android/WiFi | Android/BT | Android/BLE |
 | ------------------------------------- | ------------ | -------- | ------ | ------- | ----------- | ------------ | ---------- | ----------- |
-| QL-810W                               | QL_810W      | ❌       | ❌     | ❌      | ✅          | ❌           | ❌         | ❌          |
-| [QL-820NWB](https://amzn.to/3BXQ1aj)  | QL_820NWB    | ✅       | ※1     | ❌      | △           | ✅           | △          | ❌          |
-| [QL-820NWBc](https://amzn.to/4fjhUIe) | QL_820NWB    | ✅       | ✅     | ❌      | ❌          | ✅           | ✅         | ❌          |
-| [TD-2320D](https://amzn.to/48EFCN3)   | TD_2320D_203 | ❌       | ❌     | ❌      | △           | ❌           | ❌         | ❌          |
-| [TD-2350D](https://amzn.to/48ma6TK)   | TD_2350D_300 | ✅       | △      | △       | ✅          | ✅           | ✅         | △           |
+| QL-810W                               | QL_810W      | ✗        | ✗      | ✗       | ◯           | ✗            | ✗          | ✗           |
+| [QL-820NWB](https://amzn.to/3BXQ1aj)  | QL_820NWB    | ◯        | ※1     | ✗       | △           | ◯            | △          | ✗           |
+| [QL-820NWBc](https://amzn.to/4fjhUIe) | QL_820NWB    | ◯        | ※2     | ✗       | ✗           | ◯            | ◯          | ✗           |
+| [TD-2320D](https://amzn.to/48EFCN3)   | TD_2320D_203 | ✗        | ✗      | ✗       | △           | ✗            | ✗          | ✗           |
+| [TD-2350D](https://amzn.to/48ma6TK)   | TD_2350D_300 | ◯        | △      | △       | ◯           | ◯            | ◯          | △           |
 
-Amazon Affiliate Links: **https://amzn.to/3AiiOFT**
+Amazon Affiliate Links:　**https://amzn.to/3AiiOFT**
 
 **Supplement**
 
 |     | description                |
 | --- | -------------------------- |
-| ✅  | Supported and tested       |
+| ◯   | Supported and tested       |
 | △   | Implemented but not tested |
 | -   | Plugin is not supported    |
-| ❌  | Device is not supported    |
+| ✗   | Device is not supported    |
 | BT  | Bluetooth                  |
 | BLE | Bluetooth Low Energy       |
 
 ※1 Due to low Bluetooth version, connection is not possible with iOS. Ref: https://okbizcs.okwave.jp/brother/qa/q9932082.html
 
+※2 The iOS/BT implementation for the QL-820NWBc is in place, but it’s uncertain if it functions correctly. It’s unclear whether this is an implementation issue, as Brother’s official app also doesn’t work well.
+
+## How to install
+
+```
+% npm install @rdlabo/capacitor-brotherprint
+```
+
+## Initialize the Brother SDK
+
+### Android configuration
+
+1. Place the following files in the android folder of your Capacitor project:
+
+- `android/BrotherPrintLibrary/BrotherPrintLibrary.aar`
+- `android/BrotherPrintLibrary/build.gradle`
+
+The `BrotherPrintLibrary.aar` file is the Brother Print SDK library, which you can download from the Brother website: https://support.brother.co.jp/j/s/es/dev/ja/mobilesdk/android/index.html?c=jp&lang=ja&navi=offall&comple=on&redirect=on#ver4
+
+2. In the `android/BrotherPrintLibrary/build.gradle file`, include the following content:
+
+```
+configurations.maybeCreate(“default”)
+artifacts.add(“default”, file('BrotherPrintLibrary.aar'))
+```
+
+3. Open `android/settings.gradle` and add the following lines:
+
+```
+include ':BrotherPrintLibrary'
+project(':BrotherPrintLibrary').projectDir = new File('./BrotherPrintLibrary/')
+```
+
+These steps will integrate the Brother Print SDK with your Capacitor Android project.
+
+### iOS configuration
+
+1. Place the following files in the ios folder of your Capacitor project:
+
+- `ios/LocalPackages/BRLMPrinterKit/Sources/BRLMPrinterKit.xcframework`
+- `ios/LocalPackages/BRLMPrinterKit/BRLMPrinterKit.podspec`
+- `ios/LocalPackages/BRLMPrinterKit/Package.swift`
+
+The `BRLMPrinterKit.xcframework` file is the Brother Print SDK library, which you can download from the Brother website: https://support.brother.co.jp/j/s/es/dev/ja/mobilesdk/android/index.html?c=jp&lang=ja&navi=offall&comple=on&redirect=on#ver4
+
+`BRLMPrinterKit.podspec` content is here:
+
+```podspec
+Pod::Spec.new do |s|
+  s.name             = 'BRLMPrinterKit'
+  s.version          = '4.12.0'
+  s.homepage         = 'https://support.brother.co.jp/j/s/support/html/mobilesdk/index.html'
+  s.source           = { :path => './Sources' }
+  s.summary          = "Pod for the BRLMPrinterKit / Brother's printers"
+  s.description      = "This project is only a Pod for the Brother SDK v#{s.version}"
+  s.license          = { :type => 'MIT', :file => 'LICENSE' }
+  s.author           = { 'Masahiko Sakakibara' => 'sakakibara@rdlabo.jp' }
+  s.ios.deployment_target = '11.0'
+  s.ios.vendored_frameworks = 'Sources/BRLMPrinterKit.xcframework'
+  s.pod_target_xcconfig = { 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'arm64' }
+  s.user_target_xcconfig = { 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'arm64' }
+end
+```
+
+`Package.swift` content is here:
+
+```swift
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "BRLMPrinterKit",
+    platforms: [
+        .iOS(.v13)
+    ],
+    products: [
+        .library(name: "BRLMPrinterKit", targets: ["BRLMPrinterKit"])
+    ],
+    targets: [
+        .binaryTarget(
+            name: "BRLMPrinterKit",
+            path: "Sources/BRLMPrinterKit.xcframework"
+        )
+    ]
+)
+```
+
+2. Update the `ios/App/Podfile` file at your project.
+
+```diff
+  target 'App' do
+    capacitor_pods
+    # Add your Pods here
++   pod 'BRLMPrinterKit', :path => '../LocalPackages/BRLMPrinterKit'
+  end
+```
+
+After set, run `pod update` in the `ios` directory.
+
+## Permission configuration
+
+### Android configuration
+
+Update `AndroidManifest.xml` to include the following permissions:
+
+```diff
+- <manifest xmlns:android="http://schemas.android.com/apk/res/android">
++ <manifest xmlns:android="http://schemas.android.com/apk/res/android"
++    xmlns:tools="http://schemas.android.com/tools">
+...
++     <!-- For Bluetooth -->
++     <uses-permission android:name="android.permission.BLUETOOTH" />
++     <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
++     <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+
++     <!-- For Bluetooth Low Energy, Android 11 and earlier-->
++     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
++     <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+
++     <!-- For Bluetooth Low Energy, Android 12 and later -->
++     <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
++         android:usesPermissionFlags="neverForLocation"
++         tools:targetApi="s" />
+```
+
+More information is here: https://support.brother.co.jp/j/s/support/html/mobilesdk/guide/getting-started/getting-started-android.html
+
+### iOS configuration
+
+Update `Info.plist` to include the following permissions:
+
+```diff
++ <key>NSBluetoothAlwaysUsageDescription</key>
++ <string>【Why use Bluetooth for your app.】</string>
++ <key>NSBluetoothPeripheralUsageDescription</key>
++ <string>【Why use Bluetooth for your app.】</string>
++ <key>NSBonjourServices</key>
++ <array>
++ 	<string>_pdl-datastream._tcp</string>
++ 	<string>_printer._tcp</string>
++ 	<string>_ipp._tcp</string>
++ </array>
++ <key>NSLocalNetworkUsageDescription</key>
++ <string>【Why use WiFi for your app.】</string>
++ <key>UISupportedExternalAccessoryProtocols</key>
++ <string>com.brother.ptcbp</string>
+```
+
+More information is here: https://support.brother.co.jp/j/s/support/html/mobilesdk/guide/getting-started/getting-started-ios.html
+
+## How to use
+
+```typescript
+@Component({
+  selector: 'brother-print',
+  templateUrl: 'brother.component.html',
+  styleUrls: ['brother.component.scss'],
+})
+export class BrotherComponent implements OnInit, OnDestroy {
+  readonly #listenerHandlers: PluginListenerHandle[] = [];
+  readonly printers = signal<BRLMChannelResult[]>([]);
+
+  async ngOnInit() {
+    this.#listenerHandlers.push(
+      await BrotherPrint.addListener(BrotherPrintEventsEnum.onPrint, () => {
+        console.log('onPrint');
+      }),
+    );
+    this.#listenerHandlers.push(
+      await BrotherPrint.addListener(
+        BrotherPrintEventsEnum.onPrintError,
+        info => {
+          console.log('onPrintError');
+        },
+      ),
+    );
+    this.#listenerHandlers.push(
+      await BrotherPrint.addListener(
+        BrotherPrintEventsEnum.onPrintFailedCommunication,
+        info => {
+          console.log('onPrintFailedCommunication');
+        },
+      ),
+    );
+    this.#listenerHandlers.push(
+      await BrotherPrint.addListener(
+        BrotherPrintEventsEnum.onPrinterAvailable,
+        printer => {
+          this.printers.update(prev => [...prev, printer]);
+        },
+      ),
+    );
+  }
+
+  async ngOnDestroy() {
+    this.#listenerHandlers.forEach(handler => handler.remove());
+  }
+
+  async searchPrinter(port: BRKMPrinterPort) {
+    // This method return void. Get the printer list by listening to the event.
+    await BrotherPrint.search({
+      port,
+      searchDuration: 15, // seconds
+    });
+  }
+
+  print() {
+    if (this.printers().length === 0) {
+      console.error('No printer found');
+      return;
+    }
+
+    const defaultPrintSettings: BRLMPrintOptions = {
+      modelName: BRLMPrinterModelName.QL_820NWB,
+      labelName: BRLMPrinterLabelName.RollW62,
+      encodedImage: 'base64 removed mime-type', // base64
+      numberOfCopies: 1, // default 1
+      autoCut: true, // default true
+    };
+
+    BrotherPrint.printImage({
+      ...defaultPrintSettings,
+      ...{
+        port: this.printers()[0].port,
+        channelInfo: this.printers()[0].channelInfo,
+      },
+    });
+  }
+}
+```
+
+See demo for complete code:
+https://github.com/rdlabo-team/capacitor-brotherprint/blob/main/demo/src/app/home/home.page.ts
+
 ## API
 
 <docgen-index>
@@ -124,7 +341,7 @@ you can use it to verify whether it is currently usable.
 cancelSearchWiFiPrinter() => Promise<void>
 ```
 
-Stop an active search before its timeout, including when leaving the screen.
+Basically, it times out, so there is no need to use it. Use it when you want to run multiple connectType searches at the same time and time out any of them manually.
 
 --------------------
 
@@ -135,7 +352,7 @@ Stop an active search before its timeout, including when leaving the screen.
 cancelSearchBluetoothPrinter() => Promise<void>
 ```
 
-Stop an active search before its timeout, including when leaving the screen.
+Basically, it times out, so there is no need to use it. Use it when you want to run multiple connectType searches at the same time and time out any of them manually.
 
 --------------------
 
@@ -282,7 +499,7 @@ These are optional. If these are not set, default values are assigned by the pri
 
 #### BRLMSearchOption
 
-<code>{ /** * 'usb' is android only, and now developing. */ port: <a href="#brlmprinterport">BRLMPrinterPort</a>; /** * searchDuration is the time to end search for devices. * default is 15 seconds. * use only port is 'wifi' or 'bluetoothLowEnergy'. */ searchDuration: number; /** * Android Bluetooth Classic only. Include only devices whose Bluetooth class * reports a printer. Defaults to false; ignored for other ports and on iOS. * This does not identify Brother devices. Devices with an unknown class are excluded when true. */ bluetoothPrintersOnly?: boolean; }</code>
+<code>{ /** * 'usb' is android only, and now developing. */ port: <a href="#brlmprinterport">BRLMPrinterPort</a>; /** * searchDuration is the time to end search for devices. * default is 15 seconds. * use only port is 'wifi' or 'bluetoothLowEnergy'. */ searchDuration: number; }</code>
 
 
 #### isChannelAvailableResult
@@ -459,31 +676,3 @@ These are optional. If these are not set, default values are assigned by the pri
 | **`onPrintError`**               | <code>'onPrintError'</code>               |
 
 </docgen-api>
-
-<!-- rdlabo-docs-omit -->
-## Prerelease channels
-
-An open, non-draft pull request can be published to the npm `beta` dist-tag after its `Validation` and `Package Candidate` workflows pass. A repository owner or maintainer must add a comment whose entire body is:
-
-```text
-/beta
-```
-
-The request authorizes only the pull request head SHA that existed when the comment was added. The workflow revalidates the owner or maintainer permission and head SHA immediately before publishing. Any new commit requires CI to pass again and a fresh owner or maintainer `/beta` comment. Fork pull requests are supported. Pull requests that change a release-gating workflow cannot be beta-published until those workflow changes land on `main`.
-
-Beta versions use `<base>-beta.pr<PR number>.sha<12-character SHA>`. The candidate is built in a read-only workflow without npm publishing credentials. The privileged release workflow publishes only the validated immutable package artifact with lifecycle scripts disabled. A notification failure cannot invalidate a successful npm publish.
-
-When a pull request is merged into `main`, it is automatically published to `beta` only after the required CI and `Package Candidate` succeed for that exact merge commit. Direct pushes to `main` do not publish a candidate.
-
-Only `npm run release` creates a release tag. Stable `vX.Y.Z` tags publish to npm `latest`; revision/prerelease tags publish to `next`. Neither `beta` nor `next` publishing changes the npm `latest` dist-tag.
-
-## Maintainers
-
-- [rdlabo](https://rdlabo.dev/)
-<!-- /rdlabo-docs-omit -->
-
-<!-- rdlabo-docs-omit -->
-## License
-
-MIT
-<!-- /rdlabo-docs-omit -->