ZeppOS cross-api library

📝 Table of Contents

• About
• Usage
• Support Status
• Built Using
• Authors
• Acknowledgments
• License

Advanced Topics

• Advanced Usage
• Changes done to ts types file
• Test Status
• TODO
• Contributing
• Change Log

🧐 About

Write Once deploy on multiple API_LEVEL as minimum.

You write using API_LEVEL 3.0 then you can Change min API level of your project on the fly just with one command and same codebase.

***** Although the functionality is almost complete. Testing is not yet complete and expect to find bugs/issues. You can consider this library in beta.

***** Please report any issues found here or create a pull request. Thanks in advance

🏁 Usage

npm i zeppos-cross-api
npx zeppos-cross-api --api-level=X.0

where X is 1, 2 or 3 according to your project ( you still write your code using API_LEVEL 3) and can change the min API again as easily as running above command again with new API_LEVEL

then replace each instance of '@zepos' with 'zeppos-cross-api' and you good to go

use try and catch with new functionality with sensible fallbacks for new APIs see status for details. for example

try {
  const player = create(id.PLAYER)
} catch (error) {
  do something else
}

In addition to the modules in 3.0 There is four 5 new modules (sources here and here):

1. data-conversion contains very usefull functions like str2bin to convert from string to ArrayBuffer and bin2str for viceversa.
2. device-polyfill import in your app.js if you want to use promises and setTimeout/setInterval without worrying about api level
3. zml-base-app modified version of ZML base app
4. zml-base-page modified version of ZML base page
5. zml-base-side modified version of ZML base side

zml is recommended for usage for fetch, httprequest and other side service APIs but take care that

1. Image Convert
2. Download
3. FileTransfer

are only avaliable in 3.0+ and would throw unsupported exception in other api levels.

:dart: SUPPORT STATUS

For each of non-supported function we either have

1. ERROR => function throws an error
2. NOOP => function does nothing

For each module of each API_LEVEL there is 5 level of support:

1. 🟩 FULL
2. 🟧 PARTIAL
3. 🟥 NONE (ALL are ERROR)
4. 🟥 NONE* (ALL are NOOP)
5. N/A (not yet implemented)

| Module | 3.0 | 2.0 | 1.0 | | -------------------------------------- |:--------|:-----------|:-----------| | @zos/alarm | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/app | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/app-service | 🟩 FULL | 🟥 NONE | 🟥 NONE | | @zos/ble | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/device | 🟩 FULL | 🟩 FULL | 🟩 FULL | | @zos/display | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/fs | 🟩 FULL | 🟩 FULL | 🟩 FULL | | @zos/i18n | 🟩 FULL | 🟩 FULL | 🟥 NONE | | @zos/interaction | 🟩 FULL | 🟩 FULL | 🟩 FULL | | @zos/media | 🟩 FULL | 🟥 NONE | 🟥 NONE | | @zos/notification | 🟩 FULL | 🟥 NONE* | 🟥 NONE* | | @zos/page | 🟩 FULL | 🟩 FULL | 🟧 PARTIAL | | @zos/router | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/sensor | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/settings | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/storage | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/ui | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/user | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | @zos/utils | 🟩 FULL | 🟩 FULL | 🟩 FULL |

Listing unsupported function only for 🟧 PARTIAL and 🟥 NONE*

@zos/alarm

API_LEVEL 2.0 and 1.0:

• repeat_type in set => ERROR

@zos/app

API_LEVEL 2.0 and 1.0:

• emitCustomSystemEvent => ERROR

@zos/ble

API_LEVEL 2.0 and 1.0:

• mstBuildProfile => ERROR
• mstConnect => ERROR
• DestroyProfileInstance => ERROR
• mstDisconnect => ERROR
• mstGetConnIdByRemoteAddr => ERROR
• mstGetProfileInstance => ERROR
• mstOffAllCb => ERROR
• mstOnCharaNotification => ERROR
• mstOnCharaReadComplete => ERROR
• mstOnCharaValueArrived => ERROR
• mstOnCharaWriteComplete => ERROR
• mstOnDescValueArrived => ERROR
• mstOnDescWriteComplete => ERROR
• mstOnPrepare => ERROR
• mstOnServiceChangeBegin => ERROR
• mstOnServiceChangeEnd => ERROR
• mstPair => ERROR
• mstPrepare => ERROR
• mstReadCharacteristic => ERROR
• mstReadDescriptor => ERROR
• mstStartScan => ERROR
• mstStopScan => ERROR
• mstWriteCharacteristic => ERROR
• mstWriteDescriptor => ERROR

@zos/display

API_LEVEL 2.0 and 1.0:

• getSettings => ERROR

API_LEVEL 1.0 only:

• pauseDropWristScreenOff => NOOP (but return non-zero indicating non-sucess code)
• resetDropWristScreenOff => NOOP (but return non-zero indicating non-sucess code)
• pausePalmScreenOff => NOOP (but return non-zero indicating non-sucess code)
• resetPalmScreenOff => NOOP (but return non-zero indicating non-sucess code)

@zos/notification

API_LEVEL 2.0 and 1.0:

• notify => NOOP (return 0 for non success)
• cancel => NOOP
• getAllNotifications => NOOP (return empty array)

@zos/page

API_LEVEL 1.0:

• setScrollLock => ERROR

@zos/router

API_LEVEL 2.0 and 1.0:

• ALL SYSTEM_APP constants are undefined
• checkSystemApp => NOOP

@zos/sensor

| Sensor | 3.0 | 2.0 | 1.0 | |:---------------:|:-----------|:-----------|:--------| | Accelerometer | 🟩 FULL | 🟥 MISSING | 🟥 MISSING | | Barometer | 🟩 FULL | 🟩 FULL | 🟥 MISSING | | Battery | 🟩 FULL | 🟩 FULL | 🟩 FULL | | BloodOxygen | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | Calorie | 🟩 FULL | 🟩 FULL | 🟩 FULL | | Compass | 🟩 FULL | 🟥 MISSING | 🟥 MISSING | | Distance | 🟩 FULL | 🟩 FULL | 🟩 FULL | | FatBurning | 🟩 FULL | 🟩 FULL | 🟩 FULL | | Geolocation | 🟩 FULL | 🟧 PARTIAL | 🟥 MISSING | | Gyroscope | 🟩 FULL | 🟥 MISSING | 🟥 MISSING | | HeartRate | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | Pai | 🟩 FULL | 🟩 FULL | 🟩 FULL | | Screen | 🟩 FULL | 🟥 MISSING | 🟥 MISSING | | Sleep | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | Stand | 🟩 FULL | 🟩 FULL | 🟩 FULL | | Step | 🟩 FULL | 🟩 FULL | 🟩 FULL | | Stress | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | Time | 🟩 FULL | 🟧 PARTIAL | 🟧 PARTIAL | | Vibrator | 🟩 FULL | 🟩 FULL | 🟩 FULL | | Wear | 🟩 FULL | 🟩 FULL | 🟩 FULL | | Weather | 🟩 FULL | 🟩 FULL | 🟩 FULL | | Workout | 🟩 FULL | 🟥 MISSING | 🟥 MISSING | | WorldClock | 🟩 FULL | 🟥 MISSING | 🟩 FULL |

@zos/settings

API_LEVEL 2.0 and 1.0:

• getSystemMode => ERROR

@zos/ui

API_LEVEL 1.0:

• getImageInfo => ERROR
• redraw => NOOP
• setAppWidgetSize => ERROR
• getAppWidgetSize => ERROR

As for Wdigets: (Warning: They wont throw an error but they will return undefined for createWidget):

Not Found in 2.0 and 1.0:

• CANVAS
• PAGE_SCROLLBAR
• KEYBOARD
• PICKER

Not found in 1.0:

• POLYLINE
• PAGE_INDICATOR
• VIEW_CONTAINER

@zos/user

API_LEVEL 2.0 and 1.0:

• addHealthData => ERROR

⛏️ Built Using

• Zepp OS 3.0 - Framework
• rollup
• watchdog watch folder for changes
• modified version of prepare_all.py, app.json and other files from ZeppOS-Toolbox by melianmiko

✍️ Authors

• @mahmoudbahaa - Idea & Initial work

See also the list of contributors who participated in this project.

🎉 Acknowledgements

• Hat tip to anyone whose code was used

:memo: License

This project is under license from Apache License V2. For more details, see the LICENSE file.