general (chore): tidy for release

Author: timdrysdale

README.md

@@ -1,39 +1,80 @@
 # practable-python
 a library for connecting to experiments in python
 
-## Requirements
 
-book:
-```
-expt = practable.book(group, duration, [, type="spin"| name="spin32"])
-```
+## Example Usage
 
-experiment:
+```python
+import practable
+import numpy as np
+import matplotlib.pyplot as plt
 
-```
-expt.streams()
-```
+messages = []
+   
+#modify with actual group code and experiment name
+with practable.Experiment('g-open-xxxxx','Spinner 51', exact=True) as expt:
+    
+    # Command a step of 2 radians & collect the data
+    expt.command('{"set":"mode","to":"stop"}')
+    expt.command('{"set":"mode","to":"position"}')
+    expt.command('{"set":"parameters","kp":1,"ki":0,"kd":0}')
 
-list the streams the experiment has
+    time.sleep(0.5)
+        
+    expt.command('{"set":"position","to":2}')    
+    
+    expt.ignore(0.5)
+    messages = expt.collect(1.5)
+    
+    # Process the data
+    ts = expt.extract_series(messages, "t")
+    ds = expt.extract_series(messages, "d")
+    cs = expt.extract_series(messages, "c")
+    
+    t = np.array(ts)
+    t = t - t[0]
+    
+    # Plot the data
+    plt.figure()        
+    plt.plot(t/1e3,ds,'-b',label="position")
+    plt.plot(t/1e3,cs,':r',label="set point")
+    plt.xlabel("time(s)")
+    plt.ylabel("position(rad)")
+    plt.legend()
+    plt.savefig('spinner.jpg',dpi=300)
 
 ```
-stream = expt.connect(stream_name) 
-```
-connect to experiment stream
 
+This script produces the following text output
 ```
-stream.ok()
+Command: {"set":"mode","to":"stop"}
+Command: {"set":"mode","to":"position"}
+Command: {"set":"parameters","kp":1,"ki":0,"kd":0}
+Command: {"set":"position","to":2}
+Ignoring messages for 0.5 seconds |██████████████████████████████████████████████████| 100.0% Complete
+
+Collecting messages for 1.5 seconds |██████████████████████████████████████████████████| 100.0% Complete
+
 ```
-check if stream is connected, within the session time
+An a graph:
 
+![Example graphic from a spinner](./img/spinner.jpg)
 
-Stream should be a generator (iterator) with ability to send and receive messages
+## Additional information
+
+A user name is obtained and stored locally.
+
+Bookings last only as long as the experiment is needed, because they are cancelled when the `with` environment exits. The default booking duration is 3 min.
+
+You can use an existing booking by specifying `user="cxxxxxxxxxx"` where the username is found on the `user` tab of the booking system that holds the booking.
+
+Other `practable` instances can be accessed by specifying it e.g. `booking-server="https://some.booking.server"`
+
+## Requirements
+
+Recommend python >= 3.8 because we're using websockets 12.0
 
-```
-next(stream)
 
-stream.send(message)
-```
 
 
 

img/spinner.jpg

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "practable"
-version = "0.0.9"
+version = "0.0.10"
 authors = [
   { name="Timothy Drysdale", email="timothy.d.drysdale@gmail.com" },
 ]