commit caf209981a5ed499c6579404795eb3642627d607 Author: chernov Date: Tue Mar 5 12:10:53 2024 +0300 Initial commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +book diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..99f68c3 --- /dev/null +++ b/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["chernov"] +language = "en" +multilingual = false +src = "src" +title = "Controls-kt" \ No newline at end of file diff --git a/src/01-introduction/README.md b/src/01-introduction/README.md new file mode 100644 index 0000000..aa55bb7 --- /dev/null +++ b/src/01-introduction/README.md @@ -0,0 +1,14 @@ +# Introduction + +
+🚧 Черновой вариант. Здесь нет осмысленного текста. только наброски. +
+ +Общие слова + + +## Key features +- async +- dynamic structures under the hood (to do not mess with tools like CORBA, Protobuf) +- interoperation with [Tango-CS](../advanced/tango-interop.md) + diff --git a/src/02-getting-started/01-setup.md b/src/02-getting-started/01-setup.md new file mode 100644 index 0000000..013c4c1 --- /dev/null +++ b/src/02-getting-started/01-setup.md @@ -0,0 +1,75 @@ +# Setting up the project +For quick start we provide a minimal working [boilerplate](https://github.com/kapot65/controls-kt-boilerplate) project with controls-kt. We are going to use it as a base for our tutorial. Follow the next preparation steps: +```shell +git clone https://github.com/kapot65/controls-kt-boilerplate.git +``` +After cloning you will have a project structure like this: +``` +controls-kt-boilerplate/ +├── build.gradle.kts +├── gradle.properties +├── README.md +├── settings.gradle.kts +└── src + ├── commonMain + │   └── kotlin + │   └── devices + │   └── IDemoDevice.kt + ├── jsMain + │   ├── kotlin + │   │   └── Main.kt + │   └── resources + │   └── index.html + └── jvmMain + └── kotlin + ├── devices + │   └── DemoDevice.kt + └── Server.kt +``` +This is a common kotlin mutliplatform project with enabled `jvm` and `js` targets and some controls-kt dependencies: +- ./src/commonMain/kotlin/devices/IDemoDevice.kt - contains a demo device interface and specification of its properties and actions. +- ./src/jvmMain/kotlin/devices/DemoDevice.kt - contains a demo device implementation. +- ./src/jvmMain/kotlin/Server.kt file contains a magix server with embed device manager with installed demo device. +- ./src/jsMain/kotlin/Main.kt - contains a simple controls-kt client example. + + + + +
🚧 Work in progress + +? WASM supported ? + +? What is the recommended way to use kotlin multiplatform project with controls-kt ? +
+ +In this section we are going to work with kotlin multiplatform project. + +If you plan to use only one platfrom (jvm/native/js) you can use regular kotlin project to simplify your SCADA architecture. + + + + + + + + + + diff --git a/src/02-getting-started/02-define-device-spec.md b/src/02-getting-started/02-define-device-spec.md new file mode 100644 index 0000000..5ed46ac --- /dev/null +++ b/src/02-getting-started/02-define-device-spec.md @@ -0,0 +1,5 @@ +# Define the device specification + + +## Device interface + diff --git a/src/02-getting-started/README.md b/src/02-getting-started/README.md new file mode 100644 index 0000000..1c29fd1 --- /dev/null +++ b/src/02-getting-started/README.md @@ -0,0 +1,25 @@ +This chapter contains step-by-step tutorial teaching you how to use basic controls-kt functionality: +- define device specification (device properties, actions) +- create controls-kt event loop +- read/write device properties +- execute device actions + +During this chapter we are going to create a simple device that simulates a simple attractor in 2D space defined by the following differential equations: +``` +dx/dt = y - ax^2 +dy/dt = -x - y +``` +The device will have the following properties: +- (x, y) - coordinates as current step +- a - parameter of the attractor +and the following action: +- reset - reset the coordinates + + +## Prerequisites +- Tutorial assumes that you use IntelliJ IDEA as your IDE as currently it's the only way to work with Kotlin Multiplatform projects. + + + + + \ No newline at end of file diff --git a/src/02-getting-started/setup.md b/src/02-getting-started/setup.md new file mode 100644 index 0000000..0f003ec --- /dev/null +++ b/src/02-getting-started/setup.md @@ -0,0 +1 @@ +# Setting up the project diff --git a/src/03-reference/README.md b/src/03-reference/README.md new file mode 100644 index 0000000..4cf1a4c --- /dev/null +++ b/src/03-reference/README.md @@ -0,0 +1,3 @@ +
+🚧 Work in progress +
\ No newline at end of file diff --git a/src/03-reference/actions.md b/src/03-reference/actions.md new file mode 100644 index 0000000..4cf1a4c --- /dev/null +++ b/src/03-reference/actions.md @@ -0,0 +1,3 @@ +
+🚧 Work in progress +
\ No newline at end of file diff --git a/src/03-reference/properties.md b/src/03-reference/properties.md new file mode 100644 index 0000000..4cf1a4c --- /dev/null +++ b/src/03-reference/properties.md @@ -0,0 +1,3 @@ +
+🚧 Work in progress +
\ No newline at end of file diff --git a/src/04-advanced/README.md b/src/04-advanced/README.md new file mode 100644 index 0000000..e69de29 diff --git a/src/04-advanced/dev-build.md b/src/04-advanced/dev-build.md new file mode 100644 index 0000000..aa4c515 --- /dev/null +++ b/src/04-advanced/dev-build.md @@ -0,0 +1,44 @@ +# Use the latest build from the development branch + +Currently controls-kt is under active development. If you want to use the latest build from the development branch, you can do the following steps: + +1. Clone the repository: + ```bash + git clone -b dev https://git.sciprog.center/kscience/controls-kt.git + ``` +2. Change the [version](https://git.sciprog.center/kscience/controls-kt/src/commit/5b655a9354de5ddb4be25ee9e6be876f14f10b87/build.gradle.kts#L16) in your `build.gradle.kts` file to new unique: + ```kotlin + allprojects { + // ... + version = "0.3.0-dev-6-19-02-24-local" + // ... + } + ``` +3. Execute `publishToMavenLocal` task: + ```bash + ./gradlew publishToMavenLocal + ``` + or from Idea Gradle panel: + + ![publishToMavenLocal](./images/publishToMavenLocal.png) + + Latest version of the library will be published to your local maven repository. +4. In your project add mavenLocal() to your repositories: + ```kotlin + repositories { + mavenLocal() + mavenCentral() + // ... + } + ``` +5. Add the dependencies you need using the unique version you set in p2: + ```kotlin + // ... + dependencies { + implementation("space.kscience:controls-core:0.3.0-dev-6-19-02-24-local") + // ... + } + // ... + ``` + + diff --git a/src/04-advanced/images/publishToMavenLocal.png b/src/04-advanced/images/publishToMavenLocal.png new file mode 100644 index 0000000..b1bca15 Binary files /dev/null and b/src/04-advanced/images/publishToMavenLocal.png differ diff --git a/src/04-advanced/messages.md b/src/04-advanced/messages.md new file mode 100644 index 0000000..4cf1a4c --- /dev/null +++ b/src/04-advanced/messages.md @@ -0,0 +1,3 @@ +
+🚧 Work in progress +
\ No newline at end of file diff --git a/src/04-advanced/tango-interop.md b/src/04-advanced/tango-interop.md new file mode 100644 index 0000000..da3ecfa --- /dev/null +++ b/src/04-advanced/tango-interop.md @@ -0,0 +1,7 @@ +# Interoperability with Tango + +
+🚧 Work in progress +
+ + diff --git a/src/04-advanced/work-with-c.md b/src/04-advanced/work-with-c.md new file mode 100644 index 0000000..03722e8 --- /dev/null +++ b/src/04-advanced/work-with-c.md @@ -0,0 +1,16 @@ +# Work with c libraries + +
+🚧 Work in progress +
+ +Controls-kt can be used in kotlin native projects. As long as your devices drivers have c interface, you can controls-kt as SCADA system for your devices. + +## setting up kotlin native project +🚧 Work in progress + +## using c libraries in kotlin native +🚧 Work in progress + +drawbacks: +- even in final binaries is fully native you still need to have jvm installed on your machine to run gradle tasks \ No newline at end of file diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..7a53a33 --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,14 @@ +# Summary + +- [Introduction](./01-introduction/README.md) +- [Getting started](./02-getting-started/README.md) + - [Setting up the project](./02-getting-started/01-setup.md) + - [Define device spec](./02-getting-started/02-define-device-spec.md) +- [Reference Guide](./03-reference/README.md) + - [Device Properties](./03-reference/properties.md) + - [Device Actions](./03-reference/actions.md) +- [Advanced usage](./04-advanced/README.md) + - [Use latest dev build](./04-advanced/dev-build.md) + - [Work with c](./04-advanced/work-with-c.md) + - [Interoperability with Tango](./04-advanced/tango-interop.md) + - [Message API](./04-advanced/messages.md) \ No newline at end of file