vinzenz/servicepoint
0
0
Fork 0
mirror of https://github.com/cccb/servicepoint.git synced 2025-01-18 18:10:14 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

split README

Browse source
This commit is contained in:
Vinzenz Schroeter 2024-05-26 14:53:26 +02:00
parent 3780c2063d
commit ccbba9ad83
8 changed files with 199 additions and 146 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

155
README.md
View file

@ -1,160 +1,31 @@
# servicepoint # servicepoint
[![crates.io](https://img.shields.io/crates/v/servicepoint.svg)](https://crates.io/crates/servicepoint)
[![Crates.io Total Downloads](https://img.shields.io/crates/d/servicepoint)](https://crates.io/crates/servicepoint)
[![docs.rs](https://img.shields.io/docsrs/servicepoint)](https://docs.rs/servicepoint/latest/servicepoint/)
[![GPLv3 licensed](https://img.shields.io/crates/l/servicepoint)](./LICENSE)
In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point
Display" or "Airport Display". Display" or "Airport Display".
This repository contains a library for parsing, encoding and sending packets to this display via UDP. This repository contains a library for parsing, encoding and sending packets to this display via UDP in multiple
programming languages.
## Note on stability Take a look at the contained crates for language specific information:
This library is still in early development. | Language | Readme |
You can absolutely use it, and it works, but expect minor breaking changes with every version bump. |----------|---------------------------------------------------------------------|
Please specify the full version including patch in your Cargo.toml until 1.0 is released. | Rust | [servicepoint](crates/servicepoint/README.md) |
| C / C++ | [servicepoint_binding_c](crates/servicepoint_binding_c/README.md) |
Expect bugs and/or missing features in the language bindings for now. If you need something specific, open an issue or a pull request. | C# / F# | [servicepoint_binding_cs](crates/servicepoint_binding_cs/README.md) |
## Rust
This is where the library works the best.
Any API usage accepted by the compiler in a safe context is either safe or buggy (issues welcome)
```bash
cargo add servicepoint
```
```rust
fn main() {
// establish connection
let connection = servicepoint::Connection::open("172.23.42.29:2342")
.expect("connection failed");
// clear screen content
connection.send(servicepoint::Command::Clear.into())
.expect("send failed");
}
```
More examples are available in the repository folder and in the [Projects using the library]() section
## C / C++
The lowest common denominator. Things to keep in mind:
- This is a chainsaw. You will cut your leg.
- function names are: `sp2_` \<struct_name\> \<rust name\>.
- Use the rust documentation.
- Instances get consumed in the same way they do when writing rust / C# code. Do not use an instance after an (implicit!) free.
- Option<T> or Result<T, E> turn into nullable return values - check for NULL!
- There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable.
- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe.
```c++
#include <stdio.h>
#include "servicepoint.h"
int main(void) {
sp2_Connection *connection = sp2_connection_open("localhost:2342");
if (connection == NULL)
return 1;
sp2_PixelGrid *pixels = sp2_pixel_grid_new(sp2_PIXEL_WIDTH, sp2_PIXEL_HEIGHT);
sp2_pixel_grid_fill(pixels, true);
sp2_Command *command = sp2_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
sp2_Packet *packet = sp2_packet_from_command(command);
if (!sp2_connection_send(connection, packet))
return 1;
sp2_connection_dealloc(connection);
return 0;
}
```
## C# / F#
Uses C bindings internally to provide a similar API to rust. Things to keep in mind:
- You will get a `NullPointerException` when trying to call a method where the native instance has been consumed already (e.g. when `Send`ing a command instance twice). Send a clone instead of the original if you want to keep using it.
- Some lower-level APIs _will_ panic in native code when used improperly.
Example: manipulating the `Span<byte>` of an object after freeing the instance.
- C# specifics are documented in the library. Use the rust documentation for everything else. Naming and semantics are the same apart from CamelCase instead of kebab_case.
- You will only get rust backtraces in debug builds of the native code.
- F# is not explicitly tested. If there are usability or functionality problems, please open an issue.
- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe.
```csharp
using ServicePoint;
// using statement calls Dispose() on scope exit, which frees unmanaged instances
using var connection = Connection.Open("127.0.0.1:2342");
using var pixels = PixelGrid.New(Constants.PixelWidth, Constants.PixelHeight);
while (true)
{
pixels.Fill(true);
connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone()));
Thread.Sleep(5000);
pixels.Fill(false);
connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone()));
Thread.Sleep(5000);
}
```
### Installation
NuGet packages are not a good way to distribute native projects ([relevant issue](https://github.com/dotnet/sdk/issues/33845)).
Because of that, there is no NuGet package you can use directly.
Including this repository as a submodule and building from source is the recommended way of using the library.
```bash
git submodule add https://github.com/kaesaecracker/servicepoint.git
git commit -m "add servicepoint submodule"
```
You can now reference `servicepoint-bindings-cs/src/ServicePoint.csproj` in your project.
The rust library will automatically be built.
Please provide more information in the form of an issue if you need the build to copy a different library file for your platform.
### Installation
Copy the header to your project and compile against.
You have the choice of linking statically (recommended) or dynamically.
- The C example shows how to link statically against the `staticlib` variant.
- When linked dynamically, you have to provide the `cdylib` at runtime in the _same_ version, as there are no API/ABI guarantees yet.
## Features
This library has multiple compression libraries as optional dependencies.
If you do not need compression/decompression support you can disable those features.
In the likely case you only need one of them, you can include that one specifically.
```toml
[dependencies.servicepoint]
git = "https://github.com/kaesaecracker/servicepoint.git"
default-features = false
features = ["compression-bz"]
```
Language bindings will not know which features are available and may fail at runtime.
It is recommended to include all features for builds used outside of rust.
## Projects using the library ## Projects using the library
- screen simulator (rust): https://github.com/kaesaecracker/pixel-receiver-rs - screen simulator (rust): https://github.com/kaesaecracker/servicepoint-simulator
- tanks game (C#): https://github.com/kaesaecracker/cccb-tanks-cs - tanks game (C#): https://github.com/kaesaecracker/cccb-tanks-cs
- cellular automata slideshow (rust): https://github.com/kaesaecracker/servicepoint-life
To add yourself to the list, open a pull request. To add yourself to the list, open a pull request.
## Where is servicepoint1? ## Where is servicepoint1?
This library is a spiritual mix of a not-yet-working rust library called `servicepoint` and a bunch of working but also unfinished C# code. Because most of the API concept and a bunch of code is taken from the rust library, the result is called `servicepoint`. This library is a spiritual mix of a not-yet-working rust library called `servicepoint` and a bunch of working but also
unfinished C# code. Because most of the API concept and a bunch of code is taken from the rust library, the result is
called `servicepoint`.
## Contributing ## Contributing

2
crates/servicepoint/Cargo.toml
View file

@ -7,7 +7,7 @@ license = "GPL-3.0-or-later"
description = "A rust library for the CCCB Service Point Display." description = "A rust library for the CCCB Service Point Display."
homepage = "https://docs.rs/crate/servicepoint" homepage = "https://docs.rs/crate/servicepoint"
repository = "https://github.com/cccb/servicepoint" repository = "https://github.com/cccb/servicepoint"
readme = "../../README.md" readme = "README.md"
[lib] [lib]
crate-type = ["rlib"] crate-type = ["rlib"]

54
crates/servicepoint/README.md Normal file
View file

@ -0,0 +1,54 @@
# servicepoint
[![crates.io](https://img.shields.io/crates/v/servicepoint.svg)](https://crates.io/crates/servicepoint)
[![Crates.io Total Downloads](https://img.shields.io/crates/d/servicepoint)](https://crates.io/crates/servicepoint)
[![docs.rs](https://img.shields.io/docsrs/servicepoint)](https://docs.rs/servicepoint/latest/servicepoint/)
[![GPLv3 licensed](https://img.shields.io/crates/l/servicepoint)](../../LICENSE)
In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point
Display" or "Airport Display".
This crate contains a library for parsing, encoding and sending packets to this display via UDP.
## Examples
```rust
fn main() {
// establish connection
let connection = servicepoint::Connection::open("172.23.42.29:2342")
.expect("connection failed");
// clear screen content
connection.send(servicepoint::Command::Clear.into())
.expect("send failed");
}
```
More examples are available in the crate.
Execute `cargo run --example` for a list of available examples and `cargo run --example <name>` to run one.
## Note on stability
This library is still in early development.
You can absolutely use it, and it works, but expect minor breaking changes with every version bump.
Please specify the full version including patch in your Cargo.toml until 1.0 is released.
## Installation
```bash
cargo add servicepoint
```
## Features
This library has multiple compression libraries as optional dependencies.
If you do not need compression/decompression support you can disable those features.
In the likely case you only need one of them, you can include that one specifically.
```toml
[dependencies]
servicepoint = { version = "0.5.0", default-features = false, features = ["compression-bz"] }
```
## Everything else
Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information.

2
crates/servicepoint_binding_c/Cargo.toml
View file

@ -7,7 +7,7 @@ license = "GPL-3.0-or-later"
description = "C bindings for the servicepoint crate." description = "C bindings for the servicepoint crate."
homepage = "https://docs.rs/crate/servicepoint" homepage = "https://docs.rs/crate/servicepoint"
repository = "https://github.com/cccb/servicepoint" repository = "https://github.com/cccb/servicepoint"
readme = "../../README.md" readme = "README.md"
links = "servicepoint" links = "servicepoint"
[lib] [lib]

63
crates/servicepoint_binding_c/README.md Normal file
View file

@ -0,0 +1,63 @@
# servicepoint_binding_c
[![crates.io](https://img.shields.io/crates/v/servicepoint_binding_c.svg)](https://crates.io/crates/servicepoint)
[![Crates.io Total Downloads](https://img.shields.io/crates/d/servicepoint_binding_c)](https://crates.io/crates/servicepoint)
[![docs.rs](https://img.shields.io/docsrs/servicepoint_binding_c)](https://docs.rs/servicepoint/latest/servicepoint/)
[![GPLv3 licensed](https://img.shields.io/crates/l/servicepoint_binding_c)](../../LICENSE)
In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point
Display" or "Airport Display".
This crate contains C bindings for the `servicepoint` library, enabling users to parse, encode and send packets to this display via UDP.
## Examples
```c++
#include <stdio.h>
#include "servicepoint.h"
int main(void) {
sp2_Connection *connection = sp2_connection_open("localhost:2342");
if (connection == NULL)
return 1;
sp2_PixelGrid *pixels = sp2_pixel_grid_new(sp2_PIXEL_WIDTH, sp2_PIXEL_HEIGHT);
sp2_pixel_grid_fill(pixels, true);
sp2_Command *command = sp2_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
sp2_Packet *packet = sp2_packet_from_command(command);
if (!sp2_connection_send(connection, packet))
return 1;
sp2_connection_dealloc(connection);
return 0;
}
```
A full example including Makefile is available as part of this crate.
## Note on stability
This library is still in early development.
You can absolutely use it, and it works, but expect minor breaking changes with every version bump.
Please specify the full version including patch in your Cargo.toml until 1.0 is released.
## Installation
Copy the header to your project and compile against.
You have the choice of linking statically (recommended) or dynamically.
- The C example shows how to link statically against the `staticlib` variant.
- When linked dynamically, you have to provide the `cdylib` at runtime in the _same_ version, as there are no API/ABI guarantees yet.
## Notes on differences to rust library
- function names are: `sp2_` \<struct_name\> \<rust name\>.
- Use the rust documentation.
- Instances get consumed in the same way they do when writing rust / C# code. Do not use an instance after an (implicit!) free.
- Option<T> or Result<T, E> turn into nullable return values - check for NULL!
- There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable.
- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe.
## Everything else
Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information.

2
crates/servicepoint_binding_cs/Cargo.toml
View file

@ -3,7 +3,7 @@ name = "servicepoint_binding_cs"
version.workspace = true version.workspace = true
edition = "2021" edition = "2021"
publish = false publish = false
readme = "../../README.md" readme = "README.md"
[lib] [lib]
crate-type = ["cdylib"] crate-type = ["cdylib"]

65
crates/servicepoint_binding_cs/README.md Normal file
View file

@ -0,0 +1,65 @@
# ServicePoint
In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point
Display" or "Airport Display".
This crate contains C# bindings for the `servicepoint` library, enabling users to parse, encode and send packets to this display via UDP.
## Examples
```csharp
using ServicePoint;
// using statement calls Dispose() on scope exit, which frees unmanaged instances
using var connection = Connection.Open("127.0.0.1:2342");
using var pixels = PixelGrid.New(Constants.PixelWidth, Constants.PixelHeight);
while (true)
{
pixels.Fill(true);
connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone()));
Thread.Sleep(5000);
pixels.Fill(false);
connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone()));
Thread.Sleep(5000);
}
```
A full example including project files is available as part of this crate.
## Note on stability
This library is still in early development.
You can absolutely use it, and it works, but expect minor breaking changes with every version bump.
## Installation
NuGet packages are not a good way to distribute native projects ([relevant issue](https://github.com/dotnet/sdk/issues/33845)).
Because of that, there is no NuGet package you can use directly.
Including this repository as a submodule and building from source is the recommended way of using the library.
```bash
git submodule add https://github.com/kaesaecracker/servicepoint.git
git commit -m "add servicepoint submodule"
```
You can now reference `servicepoint-bindings-cs/src/ServicePoint.csproj` in your project.
The rust library will automatically be built.
Please provide more information in the form of an issue if you need the build to copy a different library file for your platform.
## Notes on differences to rust library
Uses C bindings internally to provide a similar API to rust. Things to keep in mind:
- You will get a `NullPointerException` when trying to call a method where the native instance has been consumed already (e.g. when `Send`ing a command instance twice). Send a clone instead of the original if you want to keep using it.
- Some lower-level APIs _will_ panic in native code when used improperly.
Example: manipulating the `Span<byte>` of an object after freeing the instance.
- C# specifics are documented in the library. Use the rust documentation for everything else. Naming and semantics are the same apart from CamelCase instead of kebab_case.
- You will only get rust backtraces in debug builds of the native code.
- F# is not explicitly tested. If there are usability or functionality problems, please open an issue.
- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe.
## Everything else
Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information.

2
crates/servicepoint_binding_cs/ServicePoint/ServicePoint.csproj
View file

@ -56,7 +56,7 @@
<ItemGroup> <ItemGroup>
<!-- include link to source code at revision --> <!-- include link to source code at revision -->
<None Include="../../../README.md" Pack="true" PackagePath="\"/> <None Include="../README.md" Pack="true" PackagePath="\"/>
<!-- add README.md to package --> <!-- add README.md to package -->
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/> <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup> </ItemGroup>